diff --git a/core/modules/user/templates/user-picture.tpl.php b/core/modules/user/templates/user-picture.tpl.php
index ee82187..f5062db 100644
--- a/core/modules/user/templates/user-picture.tpl.php
+++ b/core/modules/user/templates/user-picture.tpl.php
@@ -12,7 +12,6 @@
  *   check_plain() before use.
  *
  * @see template_preprocess_user_picture()
- *
  * @ingroup themeable
  */
 ?>
diff --git a/core/modules/user/templates/user-profile.tpl.php b/core/modules/user/templates/user-profile.tpl.php
index a7bca78..5107066 100644
--- a/core/modules/user/templates/user-profile.tpl.php
+++ b/core/modules/user/templates/user-profile.tpl.php
@@ -26,7 +26,6 @@
  *     language negotiation rule that was previously applied.
  *
  * @see template_preprocess_user_profile()
- *
  * @ingroup themeable
  */
 ?>
diff --git a/core/modules/user/tests/user_form_test.module b/core/modules/user/tests/user_form_test.module
index 5702c53..f2121b1 100644
--- a/core/modules/user/tests/user_form_test.module
+++ b/core/modules/user/tests/user_form_test.module
@@ -23,7 +23,12 @@ function user_form_test_menu() {
 }
 
 /**
- * A test form for user_validate_current_pass().
+ * Form constructor for user_validate_current_pass() test form.
+ *
+ * @param user $account
+ *   A user account object.
+ *
+ * @see user_form_test_current_password_submit()
  */
 function user_form_test_current_password($form, &$form_state, $account) {
   $account->user_form_test_field = '';
@@ -57,7 +62,7 @@ function user_form_test_current_password($form, &$form_state, $account) {
 }
 
 /**
- * Submit function for the test form for user_validate_current_pass().
+ * Form submission handler for user_form_test_current_password().
  */
 function user_form_test_current_password_submit($form, &$form_state) {
   drupal_set_message(t('The password has been validated and the form submitted successfully.'));
diff --git a/core/modules/user/user-rtl.css b/core/modules/user/user-rtl.css
index 5a1442c..7bcce19 100644
--- a/core/modules/user/user-rtl.css
+++ b/core/modules/user/user-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Right-to-left styles for the User module.
+ */
 
 #permissions td.permission {
   padding-left: 0;
diff --git a/core/modules/user/user.admin.inc b/core/modules/user/user.admin.inc
index 396f4c0..e1c622d 100644
--- a/core/modules/user/user.admin.inc
+++ b/core/modules/user/user.admin.inc
@@ -5,6 +5,17 @@
  * Admin page callback file for the user module.
  */
 
+/**
+ * Page callback: Shows the user management page.
+ *
+ * @param string $callback_arg
+ *   (optional) An action to take when viewing the page. Defaults to an empty string.
+ *
+ * @return array
+ *   A Form API renderable array.
+ *
+ * @see user_menu()
+ */
 function user_admin($callback_arg = '') {
   $op = isset($_POST['op']) ? $_POST['op'] : $callback_arg;
 
@@ -27,10 +38,10 @@ function user_admin($callback_arg = '') {
 }
 
 /**
- * Form builder; Return form for user administration filters.
+ * Form constructor for user administration filters form.
  *
- * @ingroup forms
  * @see user_filter_form_submit()
+ * @ingroup forms
  */
 function user_filter_form() {
   $session = isset($_SESSION['user_overview_filter']) ? $_SESSION['user_overview_filter'] : array();
@@ -105,7 +116,7 @@ function user_filter_form() {
 }
 
 /**
- * Process result from user administration filter form.
+ * Form submission handler for user_filter_form().
  */
 function user_filter_form_submit($form, &$form_state) {
   $op = $form_state['values']['op'];
@@ -135,11 +146,11 @@ function user_filter_form_submit($form, &$form_state) {
 }
 
 /**
- * Form builder; User administration page.
+ * Form constructor for the user administration page.
  *
- * @ingroup forms
  * @see user_admin_account_validate()
  * @see user_admin_account_submit()
+ * @ingroup forms
  */
 function user_admin_account() {
 
@@ -235,7 +246,9 @@ function user_admin_account() {
 }
 
 /**
- * Submit the user administration update form.
+ * Form submission handler for user_admin_account().
+ *
+ * @see user_admin_account_validate()
  */
 function user_admin_account_submit($form, &$form_state) {
   $operations = module_invoke_all('user_operations', $form, $form_state);
@@ -256,6 +269,11 @@ function user_admin_account_submit($form, &$form_state) {
   }
 }
 
+/**
+ * Form validation handler for user_admin_account().
+ *
+ * @see user_admin_account_submit()
+ */
 function user_admin_account_validate($form, &$form_state) {
   $form_state['values']['accounts'] = array_filter($form_state['values']['accounts']);
   if (count($form_state['values']['accounts']) == 0) {
@@ -264,10 +282,11 @@ function user_admin_account_validate($form, &$form_state) {
 }
 
 /**
- * Form builder; Configure user settings for this site.
+ * Form constructor for the user settings form.
  *
- * @ingroup forms
  * @see user_admin_settings_submit()
+ * @see user_menu()
+ * @ingroup forms
  */
 function user_admin_settings($form, &$form_state) {
   $config = config('user.settings');
@@ -690,11 +709,17 @@ function user_admin_settings_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback: administer permissions.
+ * Page callback: form constructor for the administer permissions form.
+ *
+ * @param $rid
+ *   (optional) A role ID. Defaults to NULL. When specified, the admin form will
+ *    be built for a single role. Otherwise, the form will be built for all
+ *    roles.
  *
- * @ingroup forms
  * @see user_admin_permissions_submit()
+ * @see user_menu()
  * @see theme_user_admin_permissions()
+ * @ingroup forms
  */
 function user_admin_permissions($form, $form_state, $rid = NULL) {
 
@@ -773,9 +798,7 @@ function user_admin_permissions($form, $form_state, $rid = NULL) {
 }
 
 /**
- * Save permissions selected on the administer permissions page.
- *
- * @see user_admin_permissions()
+ * Form submission handler for user_admin_permissions().
  */
 function user_admin_permissions_submit($form, &$form_state) {
   foreach ($form_state['values']['role_names'] as $rid => $name) {
@@ -863,10 +886,12 @@ function theme_user_permission_description($variables) {
 }
 
 /**
- * Form to re-order roles or add a new one.
+ * Form constructor for a form to add or reorder user roles.
  *
- * @ingroup forms
  * @see theme_user_admin_roles()
+ * @see user_admin_roles_order_submit()
+ * @see user_menu()
+ * @ingroup forms
  */
 function user_admin_roles($form, $form_state) {
   $roles = db_select('role', 'r')
@@ -936,7 +961,7 @@ function user_admin_roles($form, $form_state) {
 }
 
 /**
- * Form submit function. Update the role weights.
+ * Form submission handler for user_admin_roles().
  */
 function user_admin_roles_order_submit($form, &$form_state) {
   foreach ($form_state['values']['roles'] as $rid => $role_values) {
@@ -992,10 +1017,16 @@ function theme_user_admin_roles($variables) {
 }
 
 /**
- * Form to configure a single role.
+ * Form constructor for the role configuration form.
  *
- * @ingroup forms
+ * @param object $role
+ *   A user role object for which the role configuration form is being built.
+ *
+ * @see user_admin_role_delete_submit()
  * @see user_admin_role_submit()
+ * @see user_admin_role_validate()
+ * @see user_menu()
+ * @ingroup forms
  */
 function user_admin_role($form, $form_state, $role) {
   $form['role'] = array(
@@ -1059,14 +1090,26 @@ function user_admin_role_submit($form, &$form_state) {
 }
 
 /**
- * Form submit handler for the user_admin_role() form.
+ * Form submission handler for user_admin_role().
+ *
+ * Called when a user clicks on the 'Delete role' button. Redirects the user to
+ * a confirmation dialog.
+ *
+ * @see user_admin_role_delete_confirm()
+ * @see user_admin_role_delete_confirm_submit()
  */
 function user_admin_role_delete_submit($form, &$form_state) {
   $form_state['redirect'] = 'admin/people/roles/delete/' . $form_state['values']['role']['rid'];
 }
 
 /**
- * Form to confirm role delete operation.
+ * Form constructor for the confirm role delete form.
+ *
+ * @param object $role
+ *   A user role object that can be deleted via this this form.
+ *
+ * @see user_admin_role_delete_confirm_submit()
+ * @ingroup forms
  */
 function user_admin_role_delete_confirm($form, &$form_state, $role) {
   $form['rid'] = array(
@@ -1077,7 +1120,7 @@ function user_admin_role_delete_confirm($form, &$form_state, $role) {
 }
 
 /**
- * Form submit handler for user_admin_role_delete_confirm().
+ * Form submission handler for user_admin_role_delete_confirm().
  */
 function user_admin_role_delete_confirm_submit($form, &$form_state) {
   user_role_delete($form_state['values']['rid']);
diff --git a/core/modules/user/user.api.php b/core/modules/user/user.api.php
index 0c3002c..bdc3759 100644
--- a/core/modules/user/user.api.php
+++ b/core/modules/user/user.api.php
@@ -1,12 +1,12 @@
 <?php
 
-use Drupal\Core\Entity\EntityInterface;
-
 /**
  * @file
  * Hooks provided by the User module.
  */
 
+use Drupal\Core\Entity\EntityInterface;
+
 /**
  * @addtogroup hooks
  * @{
@@ -15,15 +15,15 @@
 /**
  * Act on user objects when loaded from the database.
  *
- * Due to the static cache in user_load_multiple() you should not use this
- * hook to modify the user properties returned by the {users} table itself
- * since this may result in unreliable results when loading from cache.
+ * Due to the static cache in user_load_multiple(), you should not use this hook
+ * to modify the user properties returned by the {users} table itself since this
+ * may result in unreliable results when loading from cache.
  *
  * @param $users
  *   An array of user objects, indexed by uid.
  *
- * @see user_load_multiple()
  * @see profile_user_load()
+ * @see user_load_multiple()
  */
 function hook_user_load($users) {
   $result = db_query('SELECT uid, foo FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
@@ -96,8 +96,8 @@ function hook_user_delete($account) {
  * @param $method
  *   The account cancellation method.
  *
- * @see user_cancel_methods()
  * @see hook_user_cancel_methods_alter()
+ * @see user_cancel_methods()
  */
 function hook_user_cancel($edit, $account, $method) {
   switch ($method) {
@@ -139,9 +139,9 @@ function hook_user_cancel($edit, $account, $method) {
  *
  * By implementing this hook, modules are able to add, customize, or remove
  * account cancellation methods. All defined methods are turned into radio
- * button form elements by user_cancel_methods() after this hook is invoked.
- * The following properties can be defined for each method:
- * - title: The radio button's title.
+ * button form elements by user_cancel_methods() after this hook is invoked. The
+ * following properties can be defined for each method:
+ * - title: (required) The radio button's title.
  * - description: (optional) A description to display on the confirmation form
  *   if the user is not allowed to select the account cancellation method. The
  *   description is NOT used for the radio button, but instead should provide
@@ -153,8 +153,8 @@ function hook_user_cancel($edit, $account, $method) {
  * @param $methods
  *   An array containing user account cancellation methods, keyed by method id.
  *
- * @see user_cancel_methods()
  * @see user_cancel_confirm_form()
+ * @see user_cancel_methods()
  */
 function hook_user_cancel_methods_alter(&$methods) {
   // Limit access to disable account and unpublish content method.
@@ -175,13 +175,12 @@ function hook_user_cancel_methods_alter(&$methods) {
 /**
  * Alter the username that is displayed for a user.
  *
- * Called by user_format_name() to allow modules to alter the username that's
- * displayed. Can be used to ensure user privacy in situations where
+ * Called by user_format_name() to allow modules to alter the username that is
+ * displayed. This hook can be used to ensure user privacy in situations where
  * $account->name is too revealing.
  *
  * @param $name
  *   The string that user_format_name() will return.
- *
  * @param $account
  *   The account object passed to user_format_name().
  *
@@ -197,19 +196,19 @@ function hook_user_format_name_alter(&$name, $account) {
 /**
  * Add mass user operations.
  *
- * This hook enables modules to inject custom operations into the mass operations
- * dropdown found at admin/people, by associating a callback function with
- * the operation, which is called when the form is submitted. The callback function
- * receives one initial argument, which is an array of the checked users.
+ * This hook enables modules to inject custom operations into the mass
+ * operations dropdown found at admin/people, by associating a callback function
+ * with the operation, which is called when the form is submitted. The callback
+ * function receives one initial argument, which is an array of the checked
+ * users.
  *
  * @return
  *   An array of operations. Each operation is an associative array that may
  *   contain the following key-value pairs:
- *   - "label": Required. The label for the operation, displayed in the dropdown menu.
- *   - "callback": Required. The function to call for the operation.
- *   - "callback arguments": Optional. An array of additional arguments to pass to
- *     the callback function.
- *
+ *   - label: The label for the operation, displayed in the dropdown menu.
+ *   - callback: The function to call for the operation.
+ *   - callback arguments: (optional) An array of additional arguments to pass
+ *     to the callback function.
  */
 function hook_user_operations() {
   $operations = array(
@@ -292,8 +291,8 @@ function hook_user_insert($account) {
  * @param $account
  *   The user account object.
  *
- * @see hook_user_presave()
  * @see hook_user_insert()
+ * @see hook_user_presave()
  */
 function hook_user_update($account) {
   db_insert('user_changes')
@@ -305,10 +304,10 @@ function hook_user_update($account) {
 }
 
 /**
- * The user just logged in.
+ * Respond to user login.
  *
  * @param $edit
- *   The array of form values submitted by the user.
+ *   The array of form values submitted by the user, passed by reference.
  * @param $account
  *   The user object on which the operation was just performed.
  */
@@ -320,7 +319,7 @@ function hook_user_login(&$edit, $account) {
 }
 
 /**
- * The user just logged out.
+ * Respond to user logout.
  *
  * @param $account
  *   The user object on which the operation was just performed.
@@ -335,7 +334,7 @@ function hook_user_logout($account) {
 }
 
 /**
- * The user's account information is being displayed.
+ * Respond when a user's account information is about to be displayed.
  *
  * The module should format its custom additions for display and add them to the
  * $account->content array.
@@ -363,11 +362,11 @@ function hook_user_view($account, $view_mode, $langcode) {
 }
 
 /**
- * The user was built; the module may modify the structured content.
+ * Allow alterations to a structured content array for a particular user.
  *
- * This hook is called after the content has been assembled in a structured array
- * and may be used for doing processing which requires that the complete user
- * content structure has been built.
+ * This hook is called after the content has been assembled in a structured
+ * array and may be used for doing processing which requires that the complete
+ * user content structure has been built.
  *
  * If the module wishes to act on the rendered HTML of the user rather than the
  * structured content array, it may use this hook to add a #post_render callback.
@@ -380,8 +379,8 @@ function hook_user_view($account, $view_mode, $langcode) {
  * @param Drupal\user\User $account
  *   The user account being rendered.
  *
- * @see user_view()
  * @see hook_entity_view_alter()
+ * @see user_view()
  */
 function hook_user_view_alter(&$build, Drupal\user\User $account) {
   // Check for the existence of a field added by another module.
@@ -395,10 +394,10 @@ function hook_user_view_alter(&$build, Drupal\user\User $account) {
 }
 
 /**
- * Inform other modules that a user role is about to be saved.
+ * Act when that a user role is about to be saved.
  *
- * Modules implementing this hook can act on the user role object before
- * it has been saved to the database.
+ * Modules implementing this hook can act on the user role object before it has
+ * been saved to the database.
  *
  * @param $role
  *   A user role object.
@@ -414,7 +413,7 @@ function hook_user_role_presave($role) {
 }
 
 /**
- * Inform other modules that a user role has been added.
+ * Respond after a user role has been added.
  *
  * Modules implementing this hook can act on the user role object when saved to
  * the database. It's recommended that you implement this hook if your module
@@ -435,7 +434,7 @@ function hook_user_role_insert($role) {
 }
 
 /**
- * Inform other modules that a user role has been updated.
+ * Act when a user role has been updated.
  *
  * Modules implementing this hook can act on the user role object when updated.
  * It's recommended that you implement this hook if your module adds additional
@@ -456,12 +455,11 @@ function hook_user_role_update($role) {
 }
 
 /**
- * Inform other modules that a user role has been deleted.
+ * Act when a user role has been deleted.
  *
- * This hook allows you act when a user role has been deleted.
- * If your module stores references to roles, it's recommended that you
- * implement this hook and delete existing instances of the deleted role
- * in your module database tables.
+ * This hook allows you act when a user role has been deleted. If your module
+ * stores references to roles, it's recommended that you implement this hook and
+ * delete existing instances of the deleted role in your module database tables.
  *
  * @param $role
  *   The $role object being deleted.
diff --git a/core/modules/user/user.css b/core/modules/user/user.css
index 866ee40..2b8ca77 100644
--- a/core/modules/user/user.css
+++ b/core/modules/user/user.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Styles for the User module.
+ */
 
 #permissions td.module {
   font-weight: bold;
diff --git a/core/modules/user/user.js b/core/modules/user/user.js
index 8e0e135..d8d82ec 100644
--- a/core/modules/user/user.js
+++ b/core/modules/user/user.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Javascript for the User module.
+ */
+
 (function ($) {
 
 "use strict";
diff --git a/core/modules/user/user.module b/core/modules/user/user.module
index c064427..b8d7471 100644
--- a/core/modules/user/user.module
+++ b/core/modules/user/user.module
@@ -1,16 +1,17 @@
 <?php
 
-use Drupal\Core\Database\Query\SelectInterface;
-use Drupal\Core\Entity\EntityInterface;
-use Drupal\file\File;
-use Drupal\Core\Template\Attribute;
-use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
-
 /**
  * @file
  * Enables the user registration and login system.
  */
 
+use Drupal\Core\Database\Query\SelectInterface;
+use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Template\Attribute;
+use Drupal\file\File;
+
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
 /**
  * Maximum length of username text field.
  */
@@ -38,7 +39,7 @@
 const USER_REGISTER_VISITORS_ADMINISTRATIVE_APPROVAL = 'visitors_admin_approval';
 
 /**
- * Implement hook_help().
+ * Implements hook_help().
  */
 function user_help($path, $arg) {
   global $user;
@@ -90,8 +91,8 @@ function user_help($path, $arg) {
  *   A text string that controls which user hook to invoke. Valid choices are:
  *   - login: Invokes hook_user_login().
  * @param $edit
- *   An associative array variable containing form values to be passed
- *   as the first parameter of the hook function.
+ *   An associative array variable containing form values to be passed by
+ *   reference as the first parameter of the hook function.
  * @param $account
  *   The user account object to be passed as the second parameter of the hook
  *   function.
@@ -181,6 +182,13 @@ function user_entity_info() {
 
 /**
  * Entity URI callback.
+ *
+ * @param object $user
+ *   A user object for which one wishes to acquire a URI.
+ *
+ * @return array
+ *   An associative array with a key of 'path' and a value of the relative path
+ *   to the requested user object.
  */
 function user_uri($user) {
   return array(
@@ -199,7 +207,7 @@ function user_uri($user) {
  * @param $entity
  *   The entity object.
  *
- * @return
+ * @return string
  *   The name of the user.
  *
  * @see user_format_name()
@@ -254,10 +262,10 @@ function user_field_extra_fields() {
  * Fetches a user object based on an external authentication source.
  *
  * @param string $authname
- *   The external authentication username.
+ *   The external authentication username as a string.
  *
  * @return
- *   A fully-loaded user object if the user is found or FALSE if not found.
+ *   A fully-loaded user object if the user is found; otherwise, FALSE.
  */
 function user_external_load($authname) {
   $uid = db_query("SELECT uid FROM {authmap} WHERE authname = :authname", array(':authname' => $authname))->fetchField();
@@ -274,23 +282,25 @@ function user_external_load($authname) {
  * 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
- * database access if loaded again during the same page request.
+ * from the database. Users are loaded into memory and will not require database
+ * access if loaded again during the same page request.
  *
  * @param array $uids
- *   (optional) An array of entity IDs. If omitted, all entities are loaded.
+ *   (optional) An array of entity IDs. Defaults to NULL. If omitted, all
+ *   entities are loaded.
  * @param bool $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.
+ *   (optional) A Boolean indicating whether the internal cache should be reset.
+ *   Use this if loading a user object which has been altered during the page
+ *   request. Defaults to FALSE.
  *
  * @return array
  *   An array of user objects, indexed by uid.
  *
+ * @see Drupal\Core\Entity\EntityFieldQuery
  * @see entity_load_multiple()
  * @see user_load()
  * @see user_load_by_mail()
  * @see user_load_by_name()
- * @see Drupal\Core\Entity\EntityFieldQuery
  */
 function user_load_multiple(array $uids = NULL, $reset = FALSE) {
   return entity_load_multiple('user', $uids, $reset);
@@ -311,8 +321,8 @@ function user_load_multiple(array $uids = NULL, $reset = FALSE) {
  * @param int $uid
  *   Integer specifying the user ID to load.
  * @param bool $reset
- *   TRUE to reset the internal cache and load from the database; FALSE
- *   (default) to load from the internal cache, if set.
+ *   (optional) TRUE to reset the internal cache and load from the database;
+ *   FALSE to load from the internal cache, if set. Defaults to FALSE.
  *
  * @return object
  *   A fully-loaded user object upon successful user load, or FALSE if the user
@@ -329,7 +339,8 @@ function user_load($uid, $reset = FALSE) {
  *
  * @param string $mail
  *   String with the account's e-mail address.
- * @return object|bool
+ *
+ * @return object|false
  *   A fully-loaded $user object upon successful user load or FALSE if user
  *   cannot be loaded.
  *
@@ -345,8 +356,8 @@ function user_load_by_mail($mail) {
  *
  * @param string $name
  *   String with the account's user name.
- * @return object|bool
- *   A fully-loaded $user object upon successful user load or FALSE if user
+ * @return object|false
+ *   A fully-loaded user object upon successful user load or FALSE if user
  *   cannot be loaded.
  *
  * @see user_load_multiple()
@@ -357,7 +368,14 @@ function user_load_by_name($name) {
 }
 
 /**
- * Verify the syntax of the given name.
+ * Verifies the syntax of the given name.
+ *
+ * @param string $name
+ *   The name to verify as a string.
+ *
+ * @return string|null
+ *   A string expressing a possible syntax issue or NULL if no syntax
+ *   validation issues were detected.
  */
 function user_validate_name($name) {
   if (!$name) {
@@ -416,7 +434,14 @@ function user_validate_picture(&$form, &$form_state) {
 }
 
 /**
- * Generate a random alphanumeric password.
+ * Generates a random alphanumeric password.
+ *
+ * @param int $length
+ *   (optional) The desired length of the generated random password. Defaults to
+ *   10 (ten).
+ *
+ * @return string
+ *   A string with the generated random alphanumeric password.
  */
 function user_password($length = 10) {
   // This variable contains the list of allowable characters for the
@@ -443,10 +468,11 @@ 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.
+ *   (optional) An array whose keys are the role IDs of interest, such as
+ *   $user->roles. Defaults to an empty array.
  *
  * @return
  *   An array indexed by role ID. Each value is an array whose keys are the
@@ -494,10 +520,11 @@ function user_role_permissions($roles = array()) {
  * @param $string
  *   The permission, such as "administer nodes", being checked for.
  * @param $account
- *   (optional) The account to check, if not given use currently logged in user.
+ *   (optional) The user account to check. Defaults to NULL. If not given, use
+ *   the currently logged in user for this access check.
  *
  * @return
- *   Boolean TRUE if the current user has the requested permission.
+ *   A Boolean value of 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
@@ -587,7 +614,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) {
@@ -698,6 +725,18 @@ function user_user_view($account) {
 
 /**
  * Sets the value of the user register and profile forms' langcode element.
+ *
+ * @param array $element
+ *  This variable is not used by this function, but is included for consistency
+ *  with similar functions in other modules.
+ * @param mixed $input
+ *   This variable is not used by this function, but is included for consistency
+ *   with similar functions in other modules.
+ * @param array $form_state
+ *   The current state of the form, passed by reference.
+ *
+ * @return string
+ *   The preferred language code.
  */
 function _user_language_selector_langcode_value($element, $input, &$form_state) {
   // Only add to the description if the form element have a description.
@@ -731,6 +770,13 @@ function user_validate_current_pass(&$form, &$form_state) {
   }
 }
 
+/**
+ * Form constructor for the user log in block.
+ *
+ * @see user_login_default_validators()
+ * @see user_login_submit()
+ * @ingroup forms
+ */
 function user_login_block($form) {
   $form['#action'] = url(current_path(), array('query' => drupal_get_destination(), 'external' => FALSE));
   $form['#id'] = 'user-login-form';
@@ -868,8 +914,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();
 
         $block['subject'] = t('Who\'s online');
@@ -913,15 +959,13 @@ function user_preprocess_block(&$variables) {
 }
 
 /**
- * Format a username.
+ * Formats a username.
  *
  * By default, the passed-in object's 'name' property is used if it exists, or
  * else, the site-defined value for the 'anonymous' variable. However, a module
  * may override this by implementing
  * hook_user_format_name_alter(&$name, $account).
  *
- * @see hook_user_format_name_alter()
- *
  * @param $account
  *   The account object for the user whose name is to be formatted.
  *
@@ -929,6 +973,8 @@ function user_preprocess_block(&$variables) {
  *   An unsanitized string with the username to display. The code receiving
  *   this result must ensure that check_plain() is called on it before it is
  *   printed to the page.
+ *
+ * @see hook_user_format_name_alter()
  */
 function user_format_name($account) {
   $name = !empty($account->name) ? $account->name : config('user.settings')->get('anonymous');
@@ -937,7 +983,7 @@ function user_format_name($account) {
 }
 
 /**
- * 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'
@@ -969,7 +1015,7 @@ function template_preprocess_user_picture(&$variables) {
     }
     if (isset($filepath)) {
       $alt = t("@user's picture", array('@user' => user_format_name($account)));
-      // If the image does not have a valid Drupal scheme (for eg. HTTP),
+      // If the image does not have a valid Drupal scheme (for e.g. HTTP),
       // don't load image styles.
       if (module_exists('image') && file_valid_uri($filepath) && $style = variable_get('user_picture_style', '')) {
         $variables['user_picture'] = theme('image_style', array('style_name' => $style, 'uri' => $filepath, 'alt' => $alt, 'title' => $alt));
@@ -1095,29 +1141,62 @@ function theme_username($variables) {
   return $output;
 }
 
+/**
+ * Returns whether the user is considered an anonymous user.
+ *
+ * @return bool
+ *   TRUE if the current user is considered anonymous; otherwise, FALSE.
+ */
 function user_is_anonymous() {
   // Menu administrators can see items for anonymous when administering.
   return !$GLOBALS['user']->uid || !empty($GLOBALS['menu_admin']);
 }
 
+/**
+ * Returns whether the user is logged in.
+ *
+ * @return bool
+ *   TRUE if the current user is logged in; otherwise, FALSE.
+ */
 function user_is_logged_in() {
   return (bool) $GLOBALS['user']->uid;
 }
 
+/**
+ * Page callback: Creates a user registration form.
+ *
+ * @return array
+ *   A FAPI array with details of the user registration form.
+ *
+ * @see user_menu()
+ */
 function user_register() {
   $account = entity_create('user', array());
   return entity_get_form($account, 'register');
 }
 
+/**
+ * Access callback: Determines whether user has permission to register.
+ *
+ * @return bool
+ *   TRUE if the current user has permission to register; otherwise, FALSE.
+ *
+ * @see user_menu()
+ */
 function user_register_access() {
   return user_is_anonymous() && (config('user.settings')->get('register') != USER_REGISTER_ADMINISTRATORS_ONLY);
 }
 
 /**
- * User view access callback.
+ * Access callback: Determines whether user can view user profiles.
  *
- * @param $account
- *   Can either be a full user object or a $uid.
+ * @param object|int $account
+ *   Can either be a full user object or a user ID.
+ *
+ * @return bool
+ *   TRUE if the user has permission to view user profile(s); otherwise, FALSE.
+ *
+ * @see user_menu()
  */
 function user_view_access($account) {
   $uid = is_object($account) ? $account->uid : (int) $account;
@@ -1140,17 +1219,31 @@ function user_view_access($account) {
 }
 
 /**
- * Access callback for user account editing.
+ * Access callback: Determines whether the user can edit account details.
+ *
+ * @param object $account
+ *   A user object.
+ *
+ * @return bool
+ *   TRUE if the user can edit user account details; otherwise, FALSE.
  */
 function user_edit_access($account) {
   return (($GLOBALS['user']->uid == $account->uid) || user_access('administer users')) && $account->uid > 0;
 }
 
 /**
- * Menu access callback; limit access to account cancellation pages.
+ * Access callback: Limits access to account cancellation pages.
+ *
+ * This function limits access to users with the 'cancel account' permission or
+ * administrative users, and prevents the anonymous user from cancelling the
+ * account.
  *
- * Limit access to users with the 'cancel account' permission or administrative
- * users, and prevent the anonymous user from cancelling the account.
+ * @param object $account
+ *   A user object.
+ *
+ * @return bool
+ *   TRUE if the user can access user account cancellation functionality;
+ *   otherwise, FALSE.
  */
 function user_cancel_access($account) {
   return ((($GLOBALS['user']->uid == $account->uid) && user_access('cancel account')) || user_access('administer users')) && $account->uid > 0;
@@ -1456,6 +1549,12 @@ function user_admin_paths() {
  *
  * Deprecated. Use %user_uid_optional instead.
  *
+ * @param mixed $arg
+ *   An argument.
+ *
+ * @return mixed
+ *   Returns a Boolean, a user ID, or the original argument passed in.
+ *
  * @todo D8: Remove.
  */
 function user_uid_only_optional_to_arg($arg) {
@@ -1463,16 +1562,18 @@ 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.
+ *   (optional) A user ID of the user to load. Defaults to NULL. If not
+ *   provided, the ID of the current user will be used.
+ *
  * @return
  *   A fully-loaded $user object upon successful user load, FALSE if user
  *   cannot be loaded.
  *
  * @see user_load()
+ *
  * @todo rethink the naming of this in Drupal 8.
  */
 function user_uid_optional_load($uid = NULL) {
@@ -1485,10 +1586,16 @@ function user_uid_optional_load($uid = NULL) {
 /**
  * Returns $arg or the user ID of the current user if $arg is '%' or empty.
  *
+ * @param mixed $arg
+ *   An argument.
+ *
+ * @return mixed
+ *   Returns a Boolean, a user ID, or the original argument passed in.
+ *
  * @todo rethink the naming of this in Drupal 8.
  */
 function user_uid_optional_to_arg($arg) {
-  // Give back the current user uid when called from eg. tracker, aka.
+  // Give back the current user uid when called from e.g. tracker, aka.
   // with an empty arg. Also use the current user uid when called from
   // the menu with a % for the current account link.
   return empty($arg) || $arg == '%' ? $GLOBALS['user']->uid : $arg;
@@ -1499,6 +1606,10 @@ function user_uid_optional_to_arg($arg) {
  *
  * Anonymous users should see a title based on the requested page, but
  * authenticated users are expected to see "My account".
+ *
+ * @return string
+ *   The title of the page to use depending upon whether the current user is
+ *   logged in, and what the current url path is.
  */
 function user_menu_title() {
   if (!user_is_logged_in()) {
@@ -1520,17 +1631,27 @@ function user_menu_title() {
 }
 
 /**
- * Menu item title callback - use the user name.
+ * Menu item title callback: Uses the user name.
+ *
+ * @param mixed $account
+ *   The user account.
+ *
+ * @return string
+ *   If $account is an object, an unsanitized string with the username to
+ *   display. The code receiving this result must ensure that check_plain() is
+ *   called on it before it is printed to the page; otherwise, an empty string.
  */
 function user_page_title($account) {
   return is_object($account) ? user_format_name($account) : '';
 }
 
 /**
- * Discover which external authentication module(s) authenticated a username.
+ * Discovers which external authentication module(s) authenticated a username.
  *
  * @param $authname
- *   A username used by an external authentication module.
+ *   (optional) A username used by an external authentication module. Defaults
+ *   to NULL.
+ *
  * @return
  *   An associative array with module as key and username as value.
  */
@@ -1540,15 +1661,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 a list of which external authentication module(s) authenticated a user.
+ *
+ * This function 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) {
@@ -1573,8 +1696,13 @@ function user_set_authmaps($account, $authmaps) {
 }
 
 /**
- * Form builder; the main user login form.
+ * Form constructor for the user login form.
  *
+ * @see user_login_authenticate_validate()
+ * @see user_login_default_validators()
+ * @see user_login_final_validate()
+ * @see user_login_name_validate()
+ * @see user_login_submit()
  * @ingroup forms
  */
 function user_login($form, &$form_state) {
@@ -1604,29 +1732,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.
+ * Returns a list of validation functions for user_login().
  *
- * We use three validators instead of one since external authentication
- * modules usually only need to alter the second validator.
+ * These validators first check for blocked users; then authenticate against
+ * records in the local database; and finally, 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.
+ *
+ * We use three validators instead of one since external authentication modules
+ * usually only need to alter the second validator.
+ *
+ * @return array
+ *   An array with a list of validate functions as values.
  *
- * @see user_login_name_validate()
  * @see user_login_authenticate_validate()
  * @see user_login_final_validate()
- * @return array
- *   A simple list of validate functions.
+ * @see user_login_name_validate()
  */
 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 user_login().
+ *
+ * Sets an error if the supplied username has been blocked.
  */
 function user_login_name_validate($form, &$form_state) {
   if (isset($form_state['values']['name']) && user_is_blocked($form_state['values']['name'])) {
@@ -1636,9 +1770,10 @@ 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 user_login().
+ *
+ * This function checks the supplied username/password against local users
+ * table. If successful, $form_state['uid'] is set to the matching user ID.
  */
 function user_login_authenticate_validate($form, &$form_state) {
   $password = trim($form_state['values']['pass']);
@@ -1647,7 +1782,7 @@ function user_login_authenticate_validate($form, &$form_state) {
     // Do not allow any login from the current user's IP if the limit has been
     // reached. Default is 50 failed attempts allowed in one hour. This is
     // independent of the per-user limit to catch attempts from one IP to log
-    // in to many different user accounts.  We have a reasonably high limit
+    // in to many different user accounts. We have a reasonably high limit
     // since there may be only one apparent IP for all users at an institution.
     if (!flood_is_allowed('failed_login_attempt_ip', $flood_config->get('ip_limit'), $flood_config->get('ip_window'))) {
       $form_state['flood_control_triggered'] = 'ip';
@@ -1682,11 +1817,11 @@ function user_login_authenticate_validate($form, &$form_state) {
 }
 
 /**
- * The final validation handler on the login form.
+ * Form validation handler for user_login().
  *
- * 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.
+ * This function 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 to be called.
  */
 function user_login_final_validate($form, &$form_state) {
   $flood_config = config('user.flood');
@@ -1720,12 +1855,13 @@ function user_login_final_validate($form, &$form_state) {
 }
 
 /**
- * Try to validate the user's login credentials locally.
+ * Attempts to validate a 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.
  */
@@ -1752,10 +1888,16 @@ function user_authenticate($name, $password) {
 }
 
 /**
- * Finalize the login process. Must be called when logging in a user.
+ * Finalizes the user login process.
  *
- * The function records a watchdog message about the new session, saves the
- * login timestamp, calls hook_user op 'login' and generates a new session. *
+ * This function must be called when logging in a user. It records a watchdog
+ * message about the new session, saves the login timestamp, and generates a new
+ * session.
+ *
+ * @param array $edit
+ *   (optional) An associative array variable containing form values to be
+ *   passed as the first parameter of the user_module_invoke() function.
+ *   This array is passed by reference. Defaults to an empty array.
  */
 function user_login_finalize(&$edit = array()) {
   global $user;
@@ -1777,9 +1919,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.
+ * Form submission handler for user_login().
+ *
+ * This function loads the user object and performs standard login tasks. The
+ * user is then redirected to the My Account page. If $_GET['destination']
+ * is set, it will override the redirect.
  */
 function user_login_submit($form, &$form_state) {
   global $user;
@@ -1790,9 +1934,17 @@ 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.
+ * Saves user details locally for users authenticated by external mechanisms.
+ *
+ * This is a helper function for authentication modules. It either logs in or
+ * registers the current user, based on username. Either way, the global $user
+ * object is populated and login tasks are performed.
+ *
+ * @param string $name
+ *   The external authentication username.
+ * @param string $module
+ *   The name of the external authentication module to use in the compound key
+ *   portion of the call to user_set_authmaps().
  */
 function user_external_login_register($name, $module) {
   $account = user_external_load($name);
@@ -1825,9 +1977,10 @@ function user_external_login_register($name, $module) {
  * @param object $account
  *   An object containing the user account.
  * @param array $options
- *   (optional) A keyed array of settings. Supported options are:
+ *   (optional) A keyed array of settings. Defaults to an empty array. Supported
+     array keys are:
  *   - langcode: A language code to be used when generating locale-sensitive
- *    URLs. If langcode is NULL the users preferred language is used.
+ *    URLs. If langcode is NULL, the user's preferred language is used.
  *
  * @return
  *   A unique URL that provides a one-time log in for the user, from which
@@ -1850,16 +2003,17 @@ function user_pass_reset_url($account, $options = array()) {
  *   - pass: The hashed user password string.
  *   - login: The user login name.
  * @param array $options
- *   (optional) A keyed array of settings. Supported options are:
+ *   (optional) A keyed array of settings. Defaults to an empty array. Supported
+ *   array keys are:
  *   - langcode: A language code to be used when generating locale-sensitive
-  *    URLs. If langcode is NULL the users preferred language is used.
+ *     URLs. If langcode is NULL, the users preferred language is used.
  *
  * @return
  *   A unique URL that may be used to confirm the cancellation of the user
  *   account.
  *
- * @see user_mail_tokens()
  * @see user_cancel_confirm()
+ * @see user_mail_tokens()
  */
 function user_cancel_url($account, $options = array()) {
   $timestamp = REQUEST_TIME;
@@ -1875,9 +2029,9 @@ function user_cancel_url($account, $options = array()) {
  * the user by email for purposes such as resetting the user's password. In
  * order to validate the URL, the same hash can be generated again, from the
  * same information, and compared to the hash value from the URL. The URL
- * normally contains both the time stamp and the numeric user ID. The login
- * name and hashed password are retrieved from the database as necessary. For a
- * usage example, see user_cancel_url() and user_cancel_confirm().
+ * normally contains both the time stamp and the numeric user ID. The login name
+ * and hashed password are retrieved from the database as necessary. For a usage
+ * example, see user_cancel_url() and user_cancel_confirm().
  *
  * @param $password
  *   The hashed user account password value.
@@ -1888,13 +2042,16 @@ function user_cancel_url($account, $options = array()) {
  *
  * @return
  *   A string that is safe for use in URLs and SQL statements.
+ *
+ * @see user_cancel_url()
+ * @see user_cancel_confirm()
  */
 function user_pass_rehash($password, $timestamp, $login) {
   return drupal_hmac_base64($timestamp . $login, drupal_get_hash_salt() . $password);
 }
 
 /**
- * Cancel a user account.
+ * Cancels a user account.
  *
  * Since the user cancellation process needs to be run in a batch, either
  * Form API will invoke it, or batch_process() needs to be invoked after calling
@@ -1908,6 +2065,7 @@ function user_pass_rehash($password, $timestamp, $login) {
  *   The account cancellation method to use.
  *
  * @see _user_cancel()
+ * @ingroup batch
  */
 function user_cancel($edit, $uid, $method) {
   global $user;
@@ -1996,7 +2154,7 @@ function _user_cancel($edit, $account, $method) {
 }
 
 /**
- * Delete a user.
+ * Deletes a user.
  *
  * @param $uid
  *   A user ID.
@@ -2006,20 +2164,27 @@ function user_delete($uid) {
 }
 
 /**
- * Delete multiple user accounts.
+ * Deletes multiple user accounts.
  *
  * @param $uids
  *   An array of user IDs.
  *
- * @see hook_user_predelete()
  * @see hook_user_delete()
+ * @see hook_user_predelete()
  */
 function user_delete_multiple(array $uids) {
   entity_get_controller('user')->delete($uids);
 }
 
 /**
- * Page callback wrapper for user_view().
+ * Page callback: Creates a wrapper for user_view().
+ *
+ * @param mixed $account
+ *   The user object.
+ *
+ * @throws Symfony\Component\HttpKernel\Exception\NotFoundHttpException
+ *
+ * @see user_menu()
  */
 function user_view_page($account) {
   if (is_object($account)) {
@@ -2031,7 +2196,7 @@ 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:
  *
@@ -2048,10 +2213,10 @@ function user_view_page($account) {
  * @param $account
  *   A user object.
  * @param $view_mode
- *   View mode, e.g. 'full'.
+ *   (optional) View mode, e.g. 'full'. Defaults to 'full'.
  * @param $langcode
- *   (optional) A language code to use for rendering. Defaults to the global
- *   content language of the current request.
+ *   (optional) A language code to use for rendering. Defaults to NUll, which
+ *   is the global content language of the current request.
  *
  * @return
  *   An array as expected by drupal_render().
@@ -2066,10 +2231,10 @@ function user_view($account, $view_mode = 'full', $langcode = NULL) {
  * @param $accounts
  *   An array of user accounts as returned by user_load_multiple().
  * @param $view_mode
- *   (optional) View mode, e.g., 'full', 'teaser'... Defaults to 'teaser.'
+ *   (optional) View mode, e.g., 'full'. Defaults to 'full'.
  * @param $langcode
- *   (optional) A language code to use for rendering. Defaults to the global
- *   content language of the current request.
+ *   (optional) A language code to use for rendering. Defaults to NULL, which
+ *   is the global content language of the current request.
  *
  * @return
  *   An array in the format expected by drupal_render().
@@ -2094,9 +2259,10 @@ function user_mail($key, &$message, $params) {
  * @param string $key
  *   The config key that provides the mail text.
  * @param string $langcode
- *   (optional) A language code to use to generate the e-mail text.
+ *   (optional) A language code to use to generate the e-mail text. Defaults to
+ *   NULL, which is the global content language of the current request.
  * @param array $variables
- *   (optional) An array of token keys and values.
+ *   (optional) An array of token keys and values. Defaults to an empty array.
  *
  * @return
  *   A string value containing the text for the user.mail config key.
@@ -2111,12 +2277,12 @@ function _user_mail_text($key, $langcode = NULL, $variables = array()) {
  * Token callback to add unsafe tokens for user mails.
  *
  * 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
- * used in email messages generated by user_mail().
+ * _user_mail_text() to set up some additional tokens that can be used in e-mail
+ * messages generated by user_mail().
  *
  * @param $replacements
  *   An associative array variable containing mappings from token names to
- *   values (for use with strtr()).
+ *   values (for use with strtr()), passed by reference.
  * @param $data
  *   An associative array of token replacement values. If the 'user' element
  *   exists, it must contain a user account object with the following
@@ -2124,7 +2290,7 @@ function _user_mail_text($key, $langcode = NULL, $variables = array()) {
  *   - login: The account login name.
  *   - pass: The hashed account login password.
  * @param $options
- *   Unused parameter required by the token_replace() function.
+ *   This is an unused parameter required by the token_replace() function.
  */
 function user_mail_tokens(&$replacements, $data, $options) {
   if (isset($data['user'])) {
@@ -2133,16 +2299,15 @@ 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.
+ *   (optional) Set this to TRUE to exclude the 'anonymous' role. Defaults to
+ *   FALSE.
  * @param $permission
- *   A string containing a permission. If set, only roles containing that
- *   permission are returned.
+ *   (optional) A string containing a permission. Defaults to NULL. If set, only
+ *   roles containing that permission are returned.
  *
  * @return
  *   An associative array with the role id as the key and the role name as
@@ -2183,7 +2348,7 @@ function user_roles($membersonly = FALSE, $permission = NULL) {
 }
 
 /**
- * Fetches a user role by role ID.
+ * Fetches a user role by a role ID.
  *
  * @param $rid
  *   A string representing the role ID.
@@ -2191,6 +2356,8 @@ function user_roles($membersonly = FALSE, $permission = NULL) {
  * @return
  *   A fully-loaded role object if a role with the given ID exists, or FALSE
  *   otherwise.
+ *
+ * @see user_role_load_by_name()
  */
 function user_role_load($rid) {
   return db_select('role', 'r')
@@ -2201,16 +2368,15 @@ function user_role_load($rid) {
 }
 
 /**
- * Save a user role to the database.
+ * Saves a user role to the database.
  *
  * @param $role
  *   A role object to modify or add.
  *
  * @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 the role was created or updated. Failure to
+ *   write the user role record will return FALSE. Otherwise, either SAVED_NEW
+ *   or SAVED_UPDATED is returned depending on the operation performed.
  */
 function user_role_save($role) {
   if ($role->name) {
@@ -2250,7 +2416,7 @@ function user_role_save($role) {
 }
 
 /**
- * Delete a user role from database.
+ * Deletes a user role from the database.
  *
  * @param $role
  *   A string with the role ID.
@@ -2277,7 +2443,16 @@ function user_role_delete($role) {
 }
 
 /**
- * Menu access callback for user role deletion.
+ * Access callback: Determines if the user has permission to delete a role.
+ *
+ * @param object $role
+ *   A user role object.
+ *
+ * @return bool
+ *   TRUE if the user has permission to administer user permissions; otherwise,
+ *   FALSE.
+ *
+ * @see user_access()
  */
 function user_role_delete_access($role) {
   // Prevent the system-defined roles from being removed.
@@ -2289,7 +2464,7 @@ function user_role_delete_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.
@@ -2306,7 +2481,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
@@ -2316,10 +2491,11 @@ function user_permission_get_modules() {
  * @param $rid
  *   The ID of a user role to alter.
  * @param $permissions
- *   An associative array, where the key holds the permission name and the value
- *   determines whether to grant or revoke that permission. Any value that
- *   evaluates to TRUE will cause the permission to be granted. Any value that
- *   evaluates to FALSE will cause the permission to be revoked.
+ *   (optional) An associative array, where the key holds the permission name
+ *   and the value determines whether to grant or revoke that permission.
+ *   Defaults to an empty array. Any value that evaluates to TRUE will cause the
+ *   permission to be granted. Any value that evaluates to FALSE will cause the
+ *   permission to be revoked.
  *   @code
  *     array(
  *       'administer nodes' => 0,                // Revoke 'administer nodes'
@@ -2348,12 +2524,12 @@ 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.
  * @param $permissions
- *   A list of permission names to grant.
+ *   (optional) A list of permission names to grant. Defaults to an empty array.
  *
  * @see user_role_change_permissions()
  * @see user_role_revoke_permissions()
@@ -2379,12 +2555,13 @@ 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.
  * @param $permissions
- *   A list of permission names to revoke.
+ *   (optional) A list of permission names to revoke. Defaults to an empty
+ *   array.
  *
  * @see user_role_change_permissions()
  * @see user_role_grant_permissions()
@@ -2403,6 +2580,11 @@ function user_role_revoke_permissions($rid, array $permissions = array()) {
 
 /**
  * Implements hook_user_operations().
+ *
+ * @see user_multiple_role_edit()
+ * @see user_user_operations_block()
+ * @see user_user_operations_unblock()
+ * @ingroup batch
  */
 function user_user_operations($form = array(), $form_state = array()) {
   $operations = array(
@@ -2472,6 +2654,11 @@ function user_user_operations($form = array(), $form_state = array()) {
 
 /**
  * Callback function for admin mass unblocking users.
+ *
+ * @param array $accounts
+ *   An array of user IDs.
+ *
+ * @see user_user_operations()
  */
 function user_user_operations_unblock($accounts) {
   $accounts = user_load_multiple($accounts);
@@ -2486,6 +2673,11 @@ function user_user_operations_unblock($accounts) {
 
 /**
  * Callback function for admin mass blocking users.
+ *
+ * @param array $accounts
+ *   An array of user IDs.
+ *
+ * @see user_user_operations()
  */
 function user_user_operations_block($accounts) {
   $accounts = user_load_multiple($accounts);
@@ -2503,6 +2695,15 @@ function user_user_operations_block($accounts) {
 
 /**
  * Callback function for admin mass adding/deleting a user role.
+ *
+ * @param array $accounts
+ *   An array of user IDs.
+ * @param string $operation
+ *   The name of the operation to perform.
+ * @param int $rid
+ *   The role ID.
+ *
+ * @see user_user_operations()
  */
 function user_multiple_role_edit($accounts, $operation, $rid) {
   $role_name = db_query('SELECT name FROM {role} WHERE rid = :rid', array(':rid' => $rid))->fetchField();
@@ -2539,6 +2740,12 @@ function user_multiple_role_edit($accounts, $operation, $rid) {
   }
 }
 
+/**
+ * Form constructor for the multiple account cancellation confirmation form.
+ *
+ * @see user_multiple_cancel_confirm_submit()
+ * @ingroup forms
+ */
 function user_multiple_cancel_confirm($form, &$form_state) {
   $edit = $form_state['input'];
 
@@ -2604,9 +2811,8 @@ function user_multiple_cancel_confirm($form, &$form_state) {
 }
 
 /**
- * Submit handler for mass-account cancellation form.
+ * Form submission handler for user_multiple_cancel_confirm().
  *
- * @see user_multiple_cancel_confirm()
  * @see user_cancel_confirm_form_submit()
  */
 function user_multiple_cancel_confirm_submit($form, &$form_state) {
@@ -2636,7 +2842,10 @@ function user_multiple_cancel_confirm_submit($form, &$form_state) {
 }
 
 /**
- * List user administration filters that can be applied.
+ * Lists user administration filters that can be applied.
+ *
+ * @return array
+ *   A list of filters as a keyed array of arrays.
  */
 function user_filters() {
   // Regular filters
@@ -2758,21 +2967,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 for the user's preferred language.
+ *
+ * This user preference can be set on the user account editing page, and is only
+ * available if there is more than one language enabled on the site. If the user
+ * has not specified a preferred language, then the site default langcode (or
+ * $default, if provided) is returned.
  *
  * @param $account
  *   User account to look up language for.
  * @param $type
- *   Optional string to define which preferred langcode should be used.
- *   Default to 'preferred_langcode' property.
- *   If set 'preferred_$type_langcode' is used.
+ *   (optional) A string to define which preferred langcode should be used.
+ *   Defaults to NULL which results in the 'preferred_langcode' property. If
+ *   set, 'preferred_$type_langcode' is used.
  * @param $default
- *   Optional default language code to return if the account
- *   has no valid language.
+ *   (optional) The default language code to return if the account has no valid
+ *   language. Defaults to NULL.
  */
 function user_preferred_langcode($account, $type = NULL, $default = NULL) {
   $language_list = language_list();
@@ -2791,11 +3001,7 @@ function user_preferred_langcode($account, $type = NULL, $default = NULL) {
 }
 
 /**
- * Conditionally create and send a notification email when a certain
- * operation happens on the given user account.
- *
- * @see user_mail_tokens()
- * @see drupal_mail()
+ * Sends notification emails to users.
  *
  * @param $op
  *   The operation being performed on the account. Possible values:
@@ -2814,12 +3020,15 @@ function user_preferred_langcode($account, $type = NULL, $default = NULL) {
  *   The user object of the account being notified. Must contain at
  *   least the fields 'uid', 'name', and 'mail'.
  * @param $langcode
- *   Optional language code to use for the notification, overriding account
- *   language.
+ *   (optional) The language code to use for the notification, overriding
+ *   account language. Defaults to NULL.
  *
  * @return
  *   The return value from drupal_mail_system()->mail(), if ends up being
  *   called.
+ *
+ * @see drupal_mail()
+ * @see user_mail_tokens()
  */
 function _user_mail_notify($op, $account, $langcode = NULL) {
   // By default, we always notify except for canceled and blocked.
@@ -2848,6 +3057,12 @@ function _user_mail_notify($op, $account, $langcode = NULL) {
  * elements to add the JavaScript and string translations for dynamic password
  * validation.
  *
+ * @param array $element
+ *   An FAPI array element.
+ *
+ * @return array
+ *   The modified FAPI array element.
+ *
  * @see system_element_info()
  */
 function user_form_process_password_confirm($element) {
@@ -2942,6 +3157,12 @@ function user_action_info() {
 /**
  * Blocks the current user.
  *
+ * @param object $entity
+ *   The user object, passed by reference.
+ * @param array $context
+ *   (optional) A recognized key is 'uid' which can be used to specify the user
+ *   ID if $entity->uid is not set. Defaults to an empty array.
+ *
  * @ingroup actions
  */
 function user_block_user_action(&$entity, $context = array()) {
@@ -2968,6 +3189,8 @@ function user_block_user_action(&$entity, $context = array()) {
  *
  * Add a checkbox for the 'user_register_form' instance settings on the 'Edit
  * field instance' form.
+ *
+ * @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'];
@@ -3000,9 +3223,11 @@ function user_form_field_ui_field_edit_form_alter(&$form, &$form_state, $form_id
 }
 
 /**
- * Additional submit handler for the 'Edit field instance' form.
+ * Form submission handler for field_ui_field_edit_form().
+ *
+ * Makes sure the 'user_register_form' setting is set for required fields.
  *
- * Make sure the 'user_register_form' setting is set for required fields.
+ * @see user_form_field_ui_field_edit_form_alter()
  */
 function user_form_field_ui_field_edit_form_submit($form, &$form_state) {
   $instance = $form_state['values']['instance'];
@@ -3041,10 +3266,16 @@ function user_modules_uninstalled($modules) {
 }
 
 /**
- * Helper function to rewrite the destination to avoid redirecting to login page after login.
+ * Ensures that users are not redirected to the login page after logging in.
  *
  * Third-party authentication modules may use this function to determine the
  * proper destination after a user has been properly logged in.
+ *
+ * @return array
+ *   The key will be 'destination' unless 'user/login' is found within the
+ *   desired path. In that event, the value will be set to 'user'; otherwise,
+ *   the value will be the path provided via the destination query string or,
+ *   if not available, the current path.
  */
 function user_login_destination() {
   $destination = drupal_get_destination();
@@ -3069,7 +3300,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'.
diff --git a/core/modules/user/user.pages.inc b/core/modules/user/user.pages.inc
index 90d804e..fe408a9 100644
--- a/core/modules/user/user.pages.inc
+++ b/core/modules/user/user.pages.inc
@@ -12,7 +12,16 @@
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 
 /**
- * Menu callback; Retrieve a JSON object containing autocomplete suggestions for existing users.
+ * Page callback: Retrieves autocomplete suggestions for existing users in JSON.
+ *
+ * @param string $string
+ *   (optional) Text to match against existing usernames. Defaults to an empty
+ *   string.
+ *
+ * @return Symfony\Component\HttpFoundation\JsonResponse
+ *   A JSON response object.
+ *
+ * @see user_menu()
  */
 function user_autocomplete($string = '') {
   $matches = array();
@@ -27,11 +36,12 @@ function user_autocomplete($string = '') {
 }
 
 /**
- * Form builder; Request a password reset.
+ * Form constructor for the request password reset form.
  *
- * @ingroup forms
- * @see user_pass_validate()
+ * @see user_menu()
  * @see user_pass_submit()
+ * @see user_pass_validate()
+ * @ingroup forms
  */
 function user_pass() {
   global $user;
@@ -59,6 +69,11 @@ function user_pass() {
   return $form;
 }
 
+/**
+ * Form validation handler for user_pass().
+ *
+ * @see user_pass_submit()
+ */
 function user_pass_validate($form, &$form_state) {
   $name = trim($form_state['values']['name']);
   // Try to load by email.
@@ -77,6 +92,11 @@ function user_pass_validate($form, &$form_state) {
   }
 }
 
+/**
+ * Form submission handler for user_pass().
+ *
+ * @see user_pass_validate()
+ */
 function user_pass_submit($form, &$form_state) {
   $language_interface = language(LANGUAGE_TYPE_INTERFACE);
 
@@ -93,7 +113,21 @@ function user_pass_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; process one time login link and redirects to the user page on success.
+ * Form constructor: A form to process a one-time login link.
+ *
+ * @param int $uid
+ *   Integer specifying the user ID to load.
+ * @param int timestamp
+ *   Unix datetime for when the login link was generated.
+ * @param string $hashed_pass
+ *   Unique hash value used in time-dependent per-user URLs.
+ * @param string $action
+ *   (optional) Action to take. If 'login', then the user is logged in
+ *   immediately. Defaults to NULL.
+ *
+ * @throws Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
+ *
+ * @see user_pass_reset_url()
  */
 function user_pass_reset($form, &$form_state, $uid, $timestamp, $hashed_pass, $action = NULL) {
   global $user;
@@ -169,7 +203,7 @@ function user_pass_reset($form, &$form_state, $uid, $timestamp, $hashed_pass, $a
 }
 
 /**
- * Menu callback; logs the current user out, and redirects to the home page.
+ * Page callback: Logs the current user out, and redirects to the home page.
  */
 function user_logout() {
   global $user;
@@ -185,10 +219,12 @@ function user_logout() {
 }
 
 /**
- * Process variables for user-profile.tpl.php.
+ * Processes variables for user-profile.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $account
+ * @param array $variables
+ *   An associative array contains the following arguments:
+ *   - $account: A user, node or comment object with 'name', 'uid' and 'picture'
+ *     fields.
  *
  * @see user-profile.tpl.php
  */
@@ -205,7 +241,12 @@ function template_preprocess_user_profile(&$variables) {
 }
 
 /**
- * Submit function for the 'Cancel account' button on the user edit form.
+ * Form submission handler for user_profile_form().
+ *
+ * Called when the 'Cancel account' button is clicked. Redirects the user to a
+ * confirm dialog.
+ *
+ * @see user_cancel_confirm_form()
  */
 function user_edit_cancel_submit($form, &$form_state) {
   $destination = array();
@@ -219,10 +260,13 @@ function user_edit_cancel_submit($form, &$form_state) {
 }
 
 /**
- * Form builder; confirm form for cancelling user account.
+ * Form constructor for the user cancellation confirm form.
+ *
+ * @param object $account
+ *   A user account object.
  *
- * @ingroup forms
  * @see user_edit_cancel_submit()
+ * @ingroup forms
  */
 function user_cancel_confirm_form($form, &$form_state, $account) {
   global $user;
@@ -296,9 +340,8 @@ function user_cancel_confirm_form($form, &$form_state, $account) {
 }
 
 /**
- * Submit handler for the account cancellation confirm form.
+ * Form submission handler for user_cancel_confirm_form().
  *
- * @see user_cancel_confirm_form()
  * @see user_multiple_cancel_confirm_submit()
  */
 function user_cancel_confirm_form_submit($form, &$form_state) {
@@ -328,7 +371,7 @@ function user_cancel_confirm_form_submit($form, &$form_state) {
 }
 
 /**
- * Helper function to return available account cancellation methods.
+ * Returns a list of available account cancellation methods.
  *
  * See documentation of hook_user_cancel_methods_alter().
  *
@@ -380,10 +423,22 @@ function user_cancel_methods() {
 }
 
 /**
- * Menu callback; Cancel a user account via e-mail confirmation link.
+ * Page callback: Cancels a user account via an e-mail confirmation link.
+ *
+ * @param object $account
+ *   User account to cancel.
+ * @param int $timestamp
+ *   (optional) A unix timestamp of when the cancellation request was generated.
+ *   Defaults to zero.
+ * @param string $hashed_pass
+ *   (optional) A unique hash based on the $account's password and $timestamp.
+ *   Defaults to an empty string.
+ *
+ * @throws
  *
  * @see user_cancel_confirm_form()
  * @see user_cancel_url()
+ * @see user_menu()
  */
 function user_cancel_confirm($account, $timestamp = 0, $hashed_pass = '') {
   // Time out in seconds until cancel URL expires; 24 hours = 86400 seconds.
@@ -416,6 +471,12 @@ function user_cancel_confirm($account, $timestamp = 0, $hashed_pass = '') {
  *
  * Displays user profile if user is logged in, or login form for anonymous
  * users.
+ *
+ * @return Symfony\Component\HttpFoundation\RedirectResponse|array
+ *   If $user->uid is set, a redirect response object; otherwise, an array with
+ *   details of the user_login form.
+ *
+ * @see user_menu()
  */
 function user_page() {
   global $user;
diff --git a/core/modules/user/user.permissions.js b/core/modules/user/user.permissions.js
index 15658a9..846b638 100644
--- a/core/modules/user/user.permissions.js
+++ b/core/modules/user/user.permissions.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Javascript for the user permission functionality in user module.
+ */
+
 (function ($) {
 
 "use strict";