Index: wp-includes/user.php
===================================================================
--- wp-includes/user.php	(revision 26208)
+++ wp-includes/user.php	(working copy)
@@ -11,7 +11,6 @@
  * The credentials is an array that has 'user_login', 'user_password', and
  * 'remember' indices. If the credentials is not given, then the log in form
  * will be assumed and used if set.
- *
  * The various authentication cookies will be set by this function and will be
  * set for a longer period depending on if the 'remember' credential is set to
  * true.
@@ -18,9 +17,10 @@
  *
  * @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 array|string $credentials   Optional. User info in order to sign on.
+ * @param bool|string  $secure_cookie Optional. 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 = '' ) {
 	if ( empty($credentials) ) {
@@ -67,8 +67,15 @@
 
 /**
  * Authenticate the user using the username and password.
+ *
+ * @since 2.8.0
+ *
+ * @param $user
+ * @param string $username
+ * @param string $password
+ *
+ * @return mixed|void|\WP_Error
  */
-add_filter('authenticate', 'wp_authenticate_username_password', 20, 3);
 function wp_authenticate_username_password($user, $username, $password) {
 	if ( is_a($user, 'WP_User') ) { return $user; }
 
@@ -102,9 +109,18 @@
 
 	return $user;
 }
+add_filter( 'authenticate', 'wp_authenticate_username_password', 20, 3 );
 
 /**
  * Authenticate the user using the WordPress auth cookie.
+ *
+ * @since 2.8.0
+ *
+ * @param $user
+ * @param string $username
+ * @param string $password
+ *
+ * @return \WP_Error|\WP_User WP_Error on failure, WP_User on success.
  */
 function wp_authenticate_cookie($user, $username, $password) {
 	if ( is_a($user, 'WP_User') ) { return $user; }
@@ -135,6 +151,10 @@
  * spammer, or if the user's primary blog has been marked as spam.
  *
  * @since 3.7.0
+ *
+ * @param $user
+ *
+ * @return \WP_User|\WP_Error WP_Error if spammer/spam, WP_User if clear.
  */
 function wp_authenticate_spam_check( $user ) {
 	if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) {
@@ -220,22 +240,21 @@
 
 /**
  * Retrieve user option that can be either per Site or per Network.
- *
  * If the user ID is not given, then the current user will be used instead. If
  * the user ID is given, then the user data will be retrieved. The filter for
  * the result, will also pass the original option name and finally the user data
  * object as the third parameter.
- *
  * The option will first check for the per site name and then the per Network name.
  *
  * @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
- * @uses apply_filters() Calls 'get_user_option_$option' hook with result,
- *		option parameter, and user data object.
+ * @uses  $wpdb WordPress database object for queries.
+ * @uses  apply_filters() Calls 'get_user_option_$option' hook with result,
+ *        option parameter, and user data object.
  *
- * @param string $option User option name.
- * @param int $user Optional. User ID.
- * @param bool $deprecated Use get_option() to check for an option in the options table.
+ * @param string      $option     User option name.
+ * @param int         $user       Optional. User ID.
+ * @param bool|string $deprecated Use get_option() to check for an option in the options table.
+ *
  * @return mixed
  */
 function get_user_option( $option, $user = 0, $deprecated = '' ) {
@@ -277,7 +296,8 @@
  * @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 bool True on success, false on failure.
  */
 function update_user_option( $user_id, $option_name, $newvalue, $global = false ) {
 	global $wpdb;
@@ -301,7 +321,8 @@
  * @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;
@@ -355,9 +376,11 @@
 	/**
 	 * PHP5 constructor
 	 *
-	 * @since 3.1.0
+	 * @since    3.1.0
 	 *
-	 * @param string|array $args The query variables
+	 * @param $query
+	 *
+	 * @internal param array|string $args The query variables
 	 * @return WP_User_Query
 	 */
 	function __construct( $query = null ) {
@@ -387,7 +410,7 @@
 	}
 
 	/**
-	 * Prepare the query variables
+	 * Prepare the query variables.
 	 *
 	 * @since 3.1.0
 	 * @access private