diff --git a/modules/user/user.module b/modules/user/user.module
index 9637a71..eb35379 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -76,8 +76,8 @@ function user_help($path, $arg) {
 /**
  * Invokes a user hook in every module.
  *
- * We cannot use module_invoke() for this, because the arguments need to
- * be passed by reference.
+ * We cannot use module_invoke() for this because the arguments need to be
+ * passed by reference.
  *
  * @param $type
  *   A text string that controls which user hook to invoke.  Valid choices are:
@@ -258,7 +258,7 @@ function user_external_load($authname) {
 }
 
 /**
- * Load multiple users based on certain conditions.
+ * Loads multiple users based on certain conditions.
  *
  * This function should be used whenever you need to load more than one user
  * from the database. Users are loaded into memory and will not require
@@ -267,17 +267,16 @@ function user_external_load($authname) {
  * @param $uids
  *   An array of user IDs.
  * @param $conditions
- *   (deprecated) An associative array of conditions on the {users}
- *   table, where the keys are the database fields and the values are the
- *   values those fields must have. Instead, it is preferable to use
- *   EntityFieldQuery to retrieve a list of entity IDs loadable by
- *   this function.
+ *   (deprecated) An associative array of conditions on the {users} table,
+ *   where the keys are the database fields and the values are the values those
+ *   fields must have. Instead, it is preferable to use EntityFieldQuery to
+ *   retrieve a list of entity IDs loadable by this function.
  * @param $reset
  *   A boolean indicating that the internal cache should be reset. Use this if
  *   loading a user object which has been altered during the page request.
  *
  * @return
- *   An array of user objects, indexed by uid.
+ *   An array of user objects indexed by uid.
  *
  * @see entity_load()
  * @see user_load()
@@ -299,6 +298,9 @@ function user_load_multiple($uids = array(), $conditions = array(), $reset = FAL
  */
 class UserController extends DrupalDefaultEntityController {
 
+  /**
+   * Overrides DrupalDefaultEntityController::attachLoad().
+   */
   function attachLoad(&$queried_users, $revision_id = FALSE) {
     // Build an array of user picture IDs so that these can be fetched later.
     $picture_fids = array();
@@ -357,7 +359,7 @@ class UserController extends DrupalDefaultEntityController {
  *   (default) to load from the internal cache, if set.
  *
  * @return
- *   A fully-loaded user object upon successful user load, or FALSE if the user
+ *   A fully-loaded user object upon successful user load or FALSE if the user
  *   cannot be loaded.
  *
  * @see user_load_multiple()
@@ -368,10 +370,11 @@ function user_load($uid, $reset = FALSE) {
 }
 
 /**
- * Fetch a user object by email address.
+ * Fetches a user object by e-mail address.
  *
  * @param $mail
  *   String with the account's e-mail address.
+ *
  * @return
  *   A fully-loaded $user object upon successful user load or FALSE if user
  *   cannot be loaded.
@@ -384,10 +387,11 @@ function user_load_by_mail($mail) {
 }
 
 /**
- * Fetch a user object by account name.
+ * Fetches a user object by account name.
  *
  * @param $name
  *   String with the account's user name.
+ *
  * @return
  *   A fully-loaded $user object upon successful user load or FALSE if user
  *   cannot be loaded.
@@ -400,15 +404,14 @@ function user_load_by_name($name) {
 }
 
 /**
- * Save changes to a user account or add a new user.
+ * Saves changes to a user account or add a new user.
  *
  * @param $account
- *   (optional) The user object to modify or add. If you want to modify
- *   an existing user account, you will need to ensure that (a) $account
- *   is an object, and (b) you have set $account->uid to the numeric
- *   user ID of the user account you wish to modify. If you
- *   want to create a new user account, you can set $account->is_new to
- *   TRUE or omit the $account->uid field.
+ *   (optional) The user object to modify or add. If you want to modify an
+ *   existing user account, you will need to ensure that (a) $account is an
+ *   object, and (b) you have set $account->uid to the numeric user ID of the
+ *   user account you wish to modify. If you want to create a new user account,
+ *   you can set $account->is_new to TRUE or omit the $account->uid field.
  * @param $edit
  *   An array of fields and values to save. For example array('name'
  *   => 'My name'). Key / value pairs added to the $edit['data'] will be
@@ -417,7 +420,8 @@ function user_load_by_name($name) {
  *   (optional) The category for storing profile information in.
  *
  * @return
- *   A fully-loaded $user object upon successful save or FALSE if the save failed.
+ *   A fully-loaded $user object upon successful save or FALSE if the save
+ *   failed.
  *
  * @todo D8: Drop $edit and fix user_save() to be consistent with others.
  */
@@ -624,7 +628,13 @@ function user_save($account, $edit = array(), $category = 'account') {
 }
 
 /**
- * Verify the syntax of the given name.
+ * Verifies the syntax of the given name.
+ *
+ * @param $name
+ *   The user name to validate.
+ *
+ * @return
+ *   Returns a string containing a message if name is invalid, NULL otherwise.
  */
 function user_validate_name($name) {
   if (!$name) {
@@ -642,7 +652,7 @@ function user_validate_name($name) {
   if (preg_match('/[^\x{80}-\x{F7} a-z0-9@_.\'-]/i', $name)) {
     return t('The username contains an illegal character.');
   }
-  if (preg_match('/[\x{80}-\x{A0}' .         // Non-printable ISO-8859-1 + NBSP
+  if (preg_match('/[\x{80}-\x{A0}' .        // Non-printable ISO-8859-1 + NBSP
                   '\x{AD}' .                // Soft-hyphen
                   '\x{2000}-\x{200F}' .     // Various space characters
                   '\x{2028}-\x{202F}' .     // Bidirectional text overrides
@@ -671,6 +681,8 @@ function user_validate_name($name) {
  * @return
  *   If the address is invalid, a human-readable error message is returned.
  *   If the address is valid, nothing is returned.
+ *
+ * @see user_account_form()
  */
 function user_validate_mail($mail) {
   if (!$mail) {
@@ -705,13 +717,22 @@ function user_validate_picture(&$form, &$form_state) {
 }
 
 /**
- * Generate a random alphanumeric password.
+ * Generates a random alphanumeric password.
+ *
+ * Random password will be composed of lower and upper case ASCII letters and
+ * numbers. Note that the number 0 and the letter 'O' have been removed to
+ * avoid confusion between the two. The same is true of 'I', 1, and 'l'.
+ *
+ * @param $length
+ *   Password length.
+ *
+ * @return
+ *   A string containing the password.
  */
 function user_password($length = 10) {
-  // This variable contains the list of allowable characters for the
-  // password. Note that the number 0 and the letter 'O' have been
-  // removed to avoid confusion between the two. The same is true
-  // of 'I', 1, and 'l'.
+  // This variable contains the list of allowable characters for the password.
+  // Note that the number 0 and the letter 'O' have been removed to avoid
+  // confusion between the two. The same is true of 'I', 1, and 'l'.
   $allowable_characters = 'abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789';
 
   // Zero-based count of characters in the allowable list:
@@ -736,7 +757,7 @@ function user_password($length = 10) {
 }
 
 /**
- * Determine the permissions for one or more roles.
+ * Determines the permissions for one or more roles.
  *
  * @param $roles
  *   An array whose keys are the role IDs of interest, such as $user->roles.
@@ -783,7 +804,11 @@ function user_role_permissions($roles = array()) {
 }
 
 /**
- * Determine whether the user has a given privilege.
+ * Determines whether the user has a given privilege.
+ *
+ * All permission checks in Drupal should go through this function. This way,
+ * we guarantee consistent behavior and ensure that the superuser (user 1) can
+ * perform all actions.
  *
  * @param $string
  *   The permission, such as "administer nodes", being checked for.
@@ -792,10 +817,6 @@ function user_role_permissions($roles = array()) {
  *
  * @return
  *   Boolean TRUE if the current user has the requested permission.
- *
- * All permission checks in Drupal should go through this function. This
- * way, we guarantee consistent behavior, and ensure that the superuser
- * can perform all actions.
  */
 function user_access($string, $account = NULL) {
   global $user;
@@ -901,7 +922,7 @@ function user_permission() {
 /**
  * Implements hook_file_download().
  *
- * Ensure that user pictures (avatars) are always downloadable.
+ * Ensures that user pictures (avatars) are always downloadable.
  */
 function user_file_download($uri) {
   if (strpos(file_uri_target($uri), variable_get('user_picture_path', 'pictures') . '/picture-') === 0) {
@@ -1145,10 +1166,10 @@ function user_account_form(&$form, &$form_state) {
   );
 
   $roles = array_map('check_plain', user_roles(TRUE));
-  // The disabled checkbox subelement for the 'authenticated user' role
-  // must be generated separately and added to the checkboxes element,
-  // because of a limitation in Form API not supporting a single disabled
-  // checkbox within a set of checkboxes.
+  // The disabled checkbox subelement for the 'authenticated user' role must be
+  // generated separately and added to the checkboxes element, because of a
+  // limitation in Form API not supporting a single disabled checkbox within a
+  // set of checkboxes.
   // @todo This should be solved more elegantly. See issue #119038.
   $checkbox_authenticated = array(
     '#type' => 'checkbox',
@@ -1218,7 +1239,7 @@ function user_account_form(&$form, &$form_state) {
 }
 
 /**
- * Form validation handler for the current password on the user_account_form().
+ * Form validation for the current password on the user_account_form().
  *
  * @see user_account_form()
  */
@@ -1264,7 +1285,7 @@ function user_account_form_validate($form, &$form_state) {
     $mail = trim($form_state['values']['mail']);
     form_set_value($form['account']['mail'], $mail, $form_state);
 
-    // Validate the e-mail address, and check if it is taken by an existing user.
+    // Validate the e-mail address and check if it is taken by an existing user.
     if ($error = user_validate_mail($form_state['values']['mail'])) {
       form_set_error('mail', $error);
     }
@@ -1331,6 +1352,11 @@ function user_user_categories() {
   ));
 }
 
+/**
+ * Helper function to build login form used by user block.
+ *
+ * @see user_block_info()
+ */
 function user_login_block($form) {
   $form['#action'] = url(current_path(), array('query' => drupal_get_destination(), 'external' => FALSE));
   $form['#id'] = 'user-login-form';
@@ -1457,8 +1483,8 @@ function user_block_view($delta = '') {
         // Count users active within the defined period.
         $interval = REQUEST_TIME - variable_get('user_block_seconds_online', 900);
 
-        // Perform database queries to gather online user lists. We use s.timestamp
-        // rather than u.access because it is much faster.
+        // Perform database queries to gather online user lists. We use
+        // s.timestamp rather than u.access because it is much faster.
         $authenticated_count = db_query("SELECT COUNT(DISTINCT s.uid) FROM {sessions} s WHERE s.timestamp >= :timestamp AND s.uid > 0", array(':timestamp' => $interval))->fetchField();
 
         $output = '<p>' . format_plural($authenticated_count, 'There is currently 1 user online.', 'There are currently @count users online.') . '</p>';
@@ -1478,7 +1504,7 @@ function user_block_view($delta = '') {
 }
 
 /**
- * Process variables for user-picture.tpl.php.
+ * Processes variables for user-picture.tpl.php.
  *
  * The $variables array contains the following arguments:
  * - $account: A user, node or comment object with 'name', 'uid' and 'picture'
@@ -1535,6 +1561,9 @@ function template_preprocess_user_picture(&$variables) {
  *     uid.
  *   - title: (optional) Title to pass on to theme_item_list().
  *
+ * @return
+ *   A string containing the themed user list.
+ *
  * @ingroup themeable
  */
 function theme_user_list($variables) {
@@ -1609,6 +1638,9 @@ function user_view_access($account) {
 
 /**
  * Access callback for user account editing.
+ *
+ * @param $account
+ *   A full user object.
  */
 function user_edit_access($account) {
   return (($GLOBALS['user']->uid == $account->uid) || user_access('administer users')) && $account->uid > 0;
@@ -1617,8 +1649,11 @@ function user_edit_access($account) {
 /**
  * Menu access callback; limit access to account cancellation pages.
  *
- * Limit access to users with the 'cancel account' permission or administrative
+ * Limits access to users with the 'cancel account' permission or administrative
  * users, and prevent the anonymous user from cancelling the account.
+ *
+ * @param $account
+ *   A full user object.
  */
 function user_cancel_access($account) {
   return ((($GLOBALS['user']->uid == $account->uid) && user_access('cancel account')) || user_access('administer users')) && $account->uid > 0;
@@ -1956,13 +1991,14 @@ function user_uid_only_optional_to_arg($arg) {
 }
 
 /**
- * Load either a specified or the current user account.
+ * Loads either a specified or the current user account.
  *
  * @param $uid
  *   An optional user ID of the user to load. If not provided, the current
  *   user's ID will be used.
+ *
  * @return
- *   A fully-loaded $user object upon successful user load, FALSE if user
+ *   A fully-loaded $user object upon successful user load or FALSE if user
  *   cannot be loaded.
  *
  * @see user_load()
@@ -1976,7 +2012,7 @@ function user_uid_optional_load($uid = NULL) {
 }
 
 /**
- * Return a user object after checking if any profile category in the path exists.
+ * Returns a user object after checking if any profile category in the path exists.
  */
 function user_category_load($uid, &$map, $index) {
   static $user_categories, $accounts;
@@ -2036,17 +2072,18 @@ function user_menu_title() {
 }
 
 /**
- * Menu item title callback - use the user name.
+ * Menu item title callback - use the user name as title.
  */
 function user_page_title($account) {
   return is_object($account) ? format_username($account) : '';
 }
 
 /**
- * Discover which external authentication module(s) authenticated a username.
+ * Discovers which external authentication module(s) authenticated a username.
  *
- * @param $authname
+ * @param string $authname
  *   A username used by an external authentication module.
+ *
  * @return
  *   An associative array with module as key and username as value.
  */
@@ -2056,15 +2093,17 @@ function user_get_authmaps($authname = NULL) {
 }
 
 /**
- * Save mappings of which external authentication module(s) authenticated
- * a user. Maps external usernames to user ids in the users table.
+ * Saves record of which external authentication module(s) authenticated a user.
+ *
+ * Maps external usernames to user ids in the users table.
  *
  * @param $account
  *   A user object.
  * @param $authmaps
  *   An associative array with a compound key and the username as the value.
- *   The key is made up of 'authname_' plus the name of the external authentication
- *   module.
+ *   The key is made up of 'authname_' plus the name of the external
+ *   authentication module.
+ *
  * @see user_external_login_register()
  */
 function user_set_authmaps($account, $authmaps) {
@@ -2123,29 +2162,35 @@ function user_login($form, &$form_state) {
 }
 
 /**
- * Set up a series for validators which check for blocked users,
- * then authenticate against local database, then return an error if
- * authentication fails. Distributed authentication modules are welcome
- * to use hook_form_alter() to change this series in order to
- * authenticate against their user database instead of the local users
- * table. If a distributed authentication module is successful, it
- * should set $form_state['uid'] to a user ID.
+ * Retrieves the sequential list of user validation functions.
  *
- * We use three validators instead of one since external authentication
- * modules usually only need to alter the second validator.
+ * Sets up a series for validators which check for blocked users, authenticates
+ * against local database, then returns an error if authentication fails.
+ * Distributed authentication modules are welcome to use hook_form_alter() to
+ * change this series in order to authenticate against their user database
+ * instead of the local users table. If a distributed authentication module is
+ * successful, it should set $form_state['uid'] to a user ID.
+ *
+ * We use three validators instead of one since external authentication modules
+ * usually only need to alter the second validator.
+ *
+ * @return
+ *   An array of validate functions.
  *
  * @see user_login_name_validate()
  * @see user_login_authenticate_validate()
  * @see user_login_final_validate()
- * @return array
- *   A simple list of validate functions.
  */
 function user_login_default_validators() {
   return array('user_login_name_validate', 'user_login_authenticate_validate', 'user_login_final_validate');
 }
 
 /**
- * A FAPI validate handler. Sets an error if supplied username has been blocked.
+ * Form validation handler for the user login form.
+ *
+ * Sets an error if supplied username has been blocked.
+ *
+ * @see user_login_default_validators()
  */
 function user_login_name_validate($form, &$form_state) {
   if (!empty($form_state['values']['name']) && user_is_blocked($form_state['values']['name'])) {
@@ -2155,9 +2200,12 @@ function user_login_name_validate($form, &$form_state) {
 }
 
 /**
- * A validate handler on the login form. Check supplied username/password
- * against local users table. If successful, $form_state['uid']
- * is set to the matching user ID.
+ * Form validation handler for the user login form.
+ *
+ * Checks supplied username/password against local users table. If successful,
+ * $form_state['uid'] is set to the matching user ID.
+ *
+ * @see user_login_default_validators()
  */
 function user_login_authenticate_validate($form, &$form_state) {
   $password = trim($form_state['values']['pass']);
@@ -2202,9 +2250,10 @@ function user_login_authenticate_validate($form, &$form_state) {
 /**
  * The final validation handler on the login form.
  *
- * Sets a form error if user has not been authenticated, or if too many
- * logins have been attempted. This validation function should always
- * be the last one.
+ * Sets a form error if user has not been authenticated, or if too many logins
+ * have been attempted. This validation function should always be the last one.
+ *
+ * @see user_login_default_validators()
  */
 function user_login_final_validate($form, &$form_state) {
   if (empty($form_state['uid'])) {
@@ -2237,14 +2286,15 @@ function user_login_final_validate($form, &$form_state) {
 }
 
 /**
- * Try to validate the user's login credentials locally.
+ * Tries to validate the user's login credentials locally.
  *
  * @param $name
  *   User name to authenticate.
  * @param $password
  *   A plain-text password, such as trimmed text from form values.
+ *
  * @return
- *   The user's uid on success, or FALSE on failure to authenticate.
+ *   The user's uid on success or FALSE on failure to authenticate.
  */
 function user_authenticate($name, $password) {
   $uid = FALSE;
@@ -2298,9 +2348,11 @@ function user_login_finalize(&$edit = array()) {
 }
 
 /**
- * Submit handler for the login form. Load $user object and perform standard login
- * tasks. The user is then redirected to the My Account page. Setting the
- * destination in the query string overrides the redirect.
+ * Submit handler for the login form.
+ *
+ * Loads global $user object and perform standard login tasks. The user is then
+ * redirected to the 'My Account' page. Setting the destination in the query
+ * string overrides the redirect.
  */
 function user_login_submit($form, &$form_state) {
   global $user;
@@ -2311,9 +2363,10 @@ function user_login_submit($form, &$form_state) {
 }
 
 /**
- * Helper function for authentication modules. Either logs in or registers
- * the current user, based on username. Either way, the global $user object is
- * populated and login tasks are performed.
+ * Helper function for authentication modules.
+ *
+ * Either logs in or registers the current user, based on username. Either way,
+ * the global $user object is populated and login tasks are performed.
  */
 function user_external_login_register($name, $module) {
   $account = user_external_load($name);
@@ -2427,9 +2480,9 @@ function user_pass_rehash($password, $timestamp, $login, $uid) {
 }
 
 /**
- * Cancel a user account.
+ * Cancels a user account.
  *
- * Since the user cancellation process needs to be run in a batch, either
+ * Since the user cancellation process needs to be run in a batch, either the
  * Form API will invoke it, or batch_process() needs to be invoked after calling
  * this function and should define the path to redirect to.
  *
@@ -2547,7 +2600,7 @@ function _user_cancel_session_regenerate() {
 }
 
 /**
- * Delete a user.
+ * Deletes a user.
  *
  * @param $uid
  *   A user ID.
@@ -2557,7 +2610,7 @@ function user_delete($uid) {
 }
 
 /**
- * Delete multiple user accounts.
+ * Deletes multiple user accounts.
  *
  * @param $uids
  *   An array of user IDs.
@@ -2596,6 +2649,9 @@ function user_delete_multiple(array $uids) {
 
 /**
  * Page callback wrapper for user_view().
+ *
+ * @param $account
+ *   A full user object.
  */
 function user_view_page($account) {
   // An administrator may try to view a non-existent account,
@@ -2604,21 +2660,17 @@ function user_view_page($account) {
 }
 
 /**
- * Generate an array for rendering the given user.
+ * Generates an array for rendering the given user.
  *
  * When viewing a user profile, the $page array contains:
- *
- * - $page['content']['Profile Category']:
- *   Profile categories keyed by their human-readable names.
- * - $page['content']['Profile Category']['profile_machine_name']:
- *   Profile fields keyed by their machine-readable names.
- * - $page['content']['user_picture']:
- *   User's rendered picture.
- * - $page['content']['summary']:
- *   Contains the default "History" profile data for a user.
- * - $page['content']['#account']:
- *   The user account of the profile being viewed.
- *
+ * - $page['content']['Profile Category']: Profile categories keyed by their
+ *   human-readable names.
+ * - $page['content']['Profile Category']['profile_machine_name']: Profile
+ *   fields keyed by their machine-readable names.
+ * - $page['content']['user_picture']: User's rendered picture.
+ * - $page['content']['summary']: Contains the default "History" profile data
+ *   for a user.
+ * - $page['content']['#account']: The user account of the profile being viewed.
  * To theme user profiles, copy modules/user/user-profile.tpl.php
  * to your theme directory, and edit it as instructed in that file's comments.
  *
@@ -2870,7 +2922,7 @@ Your account on [site:name] has been canceled.
 }
 
 /**
- * Token callback to add unsafe tokens for user mails.
+ * Callback to add to the list of tokens which are unsafe for user email.
  *
  * This function is used by the token_replace() call at the end of
  * _user_mail_text() to set up some additional tokens that can be
@@ -2898,7 +2950,7 @@ function user_mail_tokens(&$replacements, $data, $options) {
 /*** Administrative features ***********************************************/
 
 /**
- * Retrieve an array of roles matching specified conditions.
+ * Retrieves an array of roles matching specified conditions.
  *
  * @param $membersonly
  *   Set this to TRUE to exclude the 'anonymous' role.
@@ -2949,7 +3001,7 @@ function user_roles($membersonly = FALSE, $permission = NULL) {
  *   An integer representing the role ID.
  *
  * @return
- *   A fully-loaded role object if a role with the given ID exists, or FALSE
+ *   A fully-loaded role object if a role with the given ID exists or FALSE
  *   otherwise.
  *
  * @see user_role_load_by_name()
@@ -2969,7 +3021,7 @@ function user_role_load($rid) {
  *   A string representing the role name.
  *
  * @return
- *   A fully-loaded role object if a role with the given name exists, or FALSE
+ *   A fully-loaded role object if a role with the given name exists or FALSE
  *   otherwise.
  *
  * @see user_role_load()
@@ -2983,16 +3035,19 @@ function user_role_load_by_name($role_name) {
 }
 
 /**
- * Save a user role to the database.
+ * Saves a user role to the database.
  *
  * @param $role
  *   A role object to modify or add. If $role->rid is not specified, a new
  *   role will be created.
+ *
  * @return
- *   Status constant indicating if role was created or updated.
- *   Failure to write the user role record will return FALSE. Otherwise.
- *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
- *   performed.
+ *   Status constant indicating if role was created or updated. Failure to
+ *   write the user role record will return FALSE. Otherwise, SAVED_NEW or
+ *   SAVED_UPDATED is returned depending on the operation performed.
+ *
+ * @see SAVED_NEW
+ * @see SAVED_UPDATED
  */
 function user_role_save($role) {
   if ($role->name) {
@@ -3026,7 +3081,7 @@ function user_role_save($role) {
 }
 
 /**
- * Delete a user role from database.
+ * Deletes a user role from database.
  *
  * @param $role
  *   A string with the role name, or an integer with the role ID.
@@ -3059,6 +3114,12 @@ function user_role_delete($role) {
 
 /**
  * Menu access callback for user role editing.
+ *
+ * @param $role
+ *   A role object to edit.
+ *
+ * @return
+ *   TRUE if the role has 'administer permissions' permission.
  */
 function user_role_edit_access($role) {
   // Prevent the system-defined roles from being altered or removed.
@@ -3070,7 +3131,7 @@ function user_role_edit_access($role) {
 }
 
 /**
- * Determine the modules that permissions belong to.
+ * Determines the modules that permissions belong to.
  *
  * @return
  *   An associative array in the format $permission => $module.
@@ -3087,7 +3148,7 @@ function user_permission_get_modules() {
 }
 
 /**
- * Change permissions for a user role.
+ * Changes permissions for a user role.
  *
  * This function may be used to grant and revoke multiple permissions at once.
  * For example, when a form exposes checkboxes to configure permissions for a
@@ -3129,7 +3190,7 @@ function user_role_change_permissions($rid, array $permissions = array()) {
 }
 
 /**
- * Grant permissions to a user role.
+ * Grants permissions to a user role.
  *
  * @param $rid
  *   The ID of a user role to alter.
@@ -3160,7 +3221,7 @@ function user_role_grant_permissions($rid, array $permissions = array()) {
 }
 
 /**
- * Revoke permissions from a user role.
+ * Revokes permissions from a user role.
  *
  * @param $rid
  *   The ID of a user role to alter.
@@ -3253,6 +3314,9 @@ function user_user_operations($form = array(), $form_state = array()) {
 
 /**
  * Callback function for admin mass unblocking users.
+ *
+ * @param $accounts
+ *   An array of full user objects.
  */
 function user_user_operations_unblock($accounts) {
   $accounts = user_load_multiple($accounts);
@@ -3266,6 +3330,9 @@ function user_user_operations_unblock($accounts) {
 
 /**
  * Callback function for admin mass blocking users.
+ *
+ * @param $accounts
+ *   An array of full user objects.
  */
 function user_user_operations_block($accounts) {
   $accounts = user_load_multiple($accounts);
@@ -3282,6 +3349,15 @@ function user_user_operations_block($accounts) {
 
 /**
  * Callback function for admin mass adding/deleting a user role.
+ *
+ * @param $accounts
+ *   An array of full user objects.
+ * @param $operations
+ *   Operation to perform.  May be one of:
+ *   - add_role: Add role to all $accounts.
+ *   - remove: Remove role from all $accounts.
+ * @param $rid
+ *   An integer representing the role ID.
  */
 function user_multiple_role_edit($accounts, $operation, $rid) {
   // The role name is not necessary as user_save() will reload the user
@@ -3318,6 +3394,11 @@ function user_multiple_role_edit($accounts, $operation, $rid) {
   }
 }
 
+/**
+ * Form builder for mass-account cancellation form.
+ *
+ * @see user_cancel_confirm_form_submit()
+ */
 function user_multiple_cancel_confirm($form, &$form_state) {
   $edit = $form_state['input'];
 
@@ -3386,7 +3467,6 @@ function user_multiple_cancel_confirm($form, &$form_state) {
  * Submit handler for mass-account cancellation form.
  *
  * @see user_multiple_cancel_confirm()
- * @see user_cancel_confirm_form_submit()
  */
 function user_multiple_cancel_confirm_submit($form, &$form_state) {
   global $user;
@@ -3413,7 +3493,9 @@ function user_multiple_cancel_confirm_submit($form, &$form_state) {
 }
 
 /**
- * Retrieve a list of all user setting/information categories and sort them by weight.
+ * Retrieves a list of all user setting/information categories and sorts them by weight.
+ *
+ * @see hook_user_categories()
  */
 function _user_categories() {
   $categories = module_invoke_all('user_categories');
@@ -3422,6 +3504,22 @@ function _user_categories() {
   return $categories;
 }
 
+/**
+ * Comparison callback for PHP usort() function.
+ *
+ * Compares $user->weight for the two user objects.  If weights are equal,
+ * compares $user->title.
+ *
+ * @param $a
+ *   First user object.
+ * @param $b
+ *   Second user object.
+ *
+ * @return
+ *   Return an integer less than, equal to, or greater than zero if the first
+ *   argument is considered to be respectively less than, equal to, or greater
+ *   than the second.
+ */
 function _user_sort($a, $b) {
   $a = (array) $a + array('weight' => 0, 'title' => '');
   $b = (array) $b + array('weight' => 0, 'title' => '');
@@ -3429,7 +3527,7 @@ function _user_sort($a, $b) {
 }
 
 /**
- * List user administration filters that can be applied.
+ * Lists user administration filters that can be applied.
  */
 function user_filters() {
   // Regular filters
@@ -3551,17 +3649,22 @@ function theme_user_signature($variables) {
 }
 
 /**
- * Get the language object preferred by the user. This user preference can
- * be set on the user account editing page, and is only available if there
- * are more than one languages enabled on the site. If the user did not
- * choose a preferred language, or is the anonymous user, the $default
- * value, or if it is not set, the site default language will be returned.
+ * Gets the language object preferred by the user.
+ *
+ * This user preference can be set on the user account editing page, and is only
+ * available if is is more than one language enabled on the site.
  *
  * @param $account
  *   User account to look up language for.
  * @param $default
  *   Optional default language object to return if the account
  *   has no valid language.
+ *
+ * @return
+ *   A string containing the user's preferred language. If the user did not
+ *   choose a preferred language or is the anonymous user, the $default value
+ *   will be returned. If $default is not set, the site default language will
+ *   be returned.
  */
 function user_preferred_language($account, $default = NULL) {
   $language_list = language_list();
@@ -3751,8 +3854,10 @@ function user_block_user_action(&$entity, $context = array()) {
 /**
  * Implements hook_form_FORM_ID_alter().
  *
- * Add a checkbox for the 'user_register_form' instance settings on the 'Edit
- * field instance' form.
+ * Adds a checkbox for the 'user_register_form' instance settings on the 'Edit
+ * field instance' form. Adds an additional submit handler.
+ *
+ * @see user_form_field_ui_field_edit_form_submit()
  */
 function user_form_field_ui_field_edit_form_alter(&$form, &$form_state, $form_id) {
   $instance = $form['#instance'];
@@ -3787,7 +3892,7 @@ function user_form_field_ui_field_edit_form_alter(&$form, &$form_state, $form_id
 /**
  * Additional submit handler for the 'Edit field instance' form.
  *
- * Make sure the 'user_register_form' setting is set for required fields.
+ * Makes sure the 'user_register_form' setting is set for required fields.
  */
 function user_form_field_ui_field_edit_form_submit($form, &$form_state) {
   $instance = $form_state['values']['instance'];
@@ -3800,10 +3905,10 @@ function user_form_field_ui_field_edit_form_submit($form, &$form_state) {
 /**
  * Form builder; the user registration form.
  *
- * @ingroup forms
  * @see user_account_form()
  * @see user_account_form_validate()
  * @see user_register_submit()
+ * @ingroup forms
  */
 function user_register_form($form, &$form_state) {
   global $user;
@@ -3862,7 +3967,10 @@ function user_register_form($form, &$form_state) {
 }
 
 /**
- * Validation function for the user registration form.
+ * Validation handler for the user registration form.
+ *
+ * @see user_register_form()
+ * @see user_register_submit()
  */
 function user_register_validate($form, &$form_state) {
   entity_form_field_validate('user', $form, $form_state);
@@ -3871,10 +3979,11 @@ function user_register_validate($form, &$form_state) {
 /**
  * Submit handler for the user registration form.
  *
- * This function is shared by the installation form and the normal registration form,
- * which is why it can't be in the user.pages.inc file.
+ * This function is shared by the installation form and the normal registration
+ * form, which is why it can't be in the user.pages.inc file.
  *
  * @see user_register_form()
+ * @see user_register_validate()
  */
 function user_register_submit($form, &$form_state) {
   $admin = $form_state['values']['administer_users'];
@@ -4005,7 +4114,7 @@ function user_cookie_save(array $values) {
 }
 
 /**
- * Delete a visitor information cookie.
+ * Deletes a visitor information cookie.
  *
  * @param $cookie_name
  *   A cookie name such as 'homepage'.