Changeset 36245

Timestamp:

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

Author:

ericlewis

Message:

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

Fixes #35387

Location:

trunk/src/wp-includes

Files:

• pluggable.php (modified) (3 diffs)
• user.php (modified) (2 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

trunk/src/wp-includes/user.php

@@ -8 +8 @@
 
 /**
- * Authenticate user with remember capability.
+ * Authenticate and login a user with remember capability.
  *
  * The credentials is an array that has 'user_login', 'user_password', and
@@ -105 +105 @@
 
 /**
- * Authenticate the user using the username and password.
+ * Authenticate a user, confirming the username and password are valid.
  *
  * @since 2.8.0