Changeset 36245 for trunk/src/wp-includes/pluggable.php

Timestamp:

01/09/2016 08:51:13 PM (9 years ago)

Author:

ericlewis

Message:

Users: Fix incorrect docs for user authentication and login functions.

Fixes #35387

File:

• trunk/src/wp-includes/pluggable.php (modified) (3 diffs)

trunk/src/wp-includes/pluggable.php

@@ -561 +561 @@
 if ( !function_exists('wp_authenticate') ) :
 /**
- * Checks a user's login information and logs them in if it checks out.
+ * Authenticate a user, confirming the login credentials are valid.
  *
  * @since 2.5.0
  *
- * @param string $username User's username
- * @param string $password User's password
- * @return WP_User|WP_Error WP_User object if login successful, otherwise WP_Error object.
+ * @param string $username User's username.
+ * @param string $password User's password.
+ * @return WP_User|WP_Error WP_User object if the credentials are valid,
+ *                          otherwise WP_Error.
  */
 function wp_authenticate($username, $password) {
@@ -574 +575 @@
 
     /**
-     * Filter the user to authenticate.
-     *
-     * If a non-null value is passed, the filter will effectively short-circuit
-     * authentication, returning an error instead.
+     * Filter whether a set of user login credentials are valid.
+     *
+     * A WP_User object is returned if the credentials authenticate a user.
+     * WP_Error or null otherwise.
      *
      * @since 2.8.0
      *
-     * @param null|WP_User $user     User to authenticate.
-     * @param string       $username User login.
-     * @param string       $password User password
+     * @param null|WP_User|WP_Error $user     WP_User if the user is authenticated.
+     *                                        WP_Error or null otherwise.
+     * @param string                $username User login.
+     * @param string                $password User password
      */
     $user = apply_filters( 'authenticate', null, $username, $password );
@@ -842 +844 @@
 if ( !function_exists('wp_set_auth_cookie') ) :
 /**
- * Sets the authentication cookies based on user ID.
+ * Login a user by setting authentication cookies.
  *
  * The $remember parameter increases the time that the cookie will be kept. The