Ticket #26148: 26148.1.patch

wp-includes/user.php

@@ -19 +19 @@
  * @since 2.5.0
  *
  * @param array $credentials Optional. User info in order to sign on.
- * @param bool $secure_cookie Optional. Whether to use secure cookie.
- * @return object Either WP_Error on failure, or WP_User on success.
+ * @param string $secure_cookie Optional. 'true' or 'false'; whether to use secure cookie.
+ * @return \WP_Error|\WP_User WP_Error on failure, or WP_User on success.
  */
-function wp_signon( $credentials = '', $secure_cookie = '' ) {
+function wp_signon( $credentials = array(), $secure_cookie = '' ) {
         if ( empty($credentials) ) {
                 if ( ! empty($_POST['log']) )
                         $credentials['user_login'] = $_POST['log'];
@@ -99 +99 @@
         return $user;
 }
 
+add_filter( 'authenticate', 'wp_authenticate_username_password', 20, 3 );
+
 /**
  * Authenticate the user using the username and password.
+ *
+ * @since 2.8.0
+ *
+ * @param WP_User|object $user
+ * @param $username
+ * @param $password
+ *
+ * @return bool|mixed|void|WP_Error|WP_User
  */
-add_filter('authenticate', 'wp_authenticate_username_password', 20, 3);
-function wp_authenticate_username_password($user, $username, $password) {
+function wp_authenticate_username_password( $user, $username, $password ) {
         if ( is_a($user, 'WP_User') ) { return $user; }
 
         if ( empty($username) || empty($password) ) {
@@ -148 +157 @@
 
 /**
  * Authenticate the user using the WordPress auth cookie.
+ *
+ * @since 2.8.0
+ *
+ * @param WP_User|object $user
+ * @param string $username
+ * @param string $password
+ *
+ * @return WP_User|WP_Error The authenticated user, or an error.
  */
-function wp_authenticate_cookie($user, $username, $password) {
+function wp_authenticate_cookie( $user, $username, $password ) {
         if ( is_a($user, 'WP_User') ) { return $user; }
 
         if ( empty($username) && empty($password) ) {
@@ -178 +195 @@
  * spammer, or if the user's primary blog has been marked as spam.
  *
  * @since 3.7.0
+ *
+ * @param WP_User|object $user The user to check for spam.
+ *
+ * @return WP_User|WP_Error The user if clean, error if spammy.
  */
 function wp_authenticate_spam_check( $user ) {
         if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) {
@@ -341 +362 @@
  * Deletes the user option if $newvalue is empty.
  *
  * @since 2.0.0
- * @uses $wpdb WordPress database object for queries
+ * @uses $wpdb WordPress database object for queries.
+ * @see update_user_meta() for return value.
  *
- * @param int $user_id User ID
+ * @param int $user_id User ID.
  * @param string $option_name User option name.
  * @param mixed $newvalue User option value.
  * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
- * @return unknown
+ *
+ * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
  */
 function update_user_option( $user_id, $option_name, $newvalue, $global = false ) {
         global $wpdb;
@@ -366 +389 @@
  * it will prepend the WordPress table prefix to the option name.
  *
  * @since 3.0.0
- * @uses $wpdb WordPress database object for queries
+ * @uses $wpdb WordPress database object for queries.
+ * @see delete_user_meta() for return value.
  *
  * @param int $user_id User ID
  * @param string $option_name User option name.
  * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
- * @return unknown
+ *
+ * @return bool True on success, false on failure.
  */
 function delete_user_option( $user_id, $option_name, $global = false ) {
         global $wpdb;
@@ -423 +448 @@
         var $query_limit;
 
         /**
-         * PHP5 constructor
+         * PHP5 constructor.
          *
          * @since 3.1.0
          *
-         * @param string|array $args The query variables
+         * @param string|array $query Optional. The query variables.
          * @return WP_User_Query
          */
         function __construct( $query = null ) {
@@ -438 +463 @@
         }
 
         /**
-         * Prepare the query variables
+         * Prepare the query variables.
          *
          * @since 3.1.0
          *
-         * @param string|array $args The query variables
+         * @param string|array $query Optional. The query variables.
          */
         function prepare_query( $query = array() ) {
                 global $wpdb;
@@ -650 +675 @@
         }
 
         /**
-         * Execute the query, with the current variables
+         * Execute the query, with the current variables.
          *
          * @since 3.1.0
+         * @global wpdb $wpdb WordPress database object.
          */
         function query() {
                 global $wpdb;
@@ -755 +781 @@
         }
 
         /**
-         * Return the list of users
+         * Return the list of users.
          *
          * @since 3.1.0
          * @access public
@@ -767 +793 @@
         }
 
         /**
-         * Return the total number of users for the current query
+         * Return the total number of users for the current query.
          *
          * @since 3.1.0
          * @access public
@@ -803 +829 @@
  * Get the blogs a user belongs to.
  *
  * @since 3.0.0
+ * @global wpdb $wpdb The WordPress database object.
  *
- * @param int $user_id User ID
+ * @param int $user_id User ID.
  * @param bool $all Whether to retrieve all blogs, or only blogs that are not marked as deleted, archived, or spam.
  * @return array A list of the user's blogs. An empty array if the user doesn't exist or belongs to no blogs.
  */