diff --git a/core/modules/user/src/AccountForm.php b/core/modules/user/src/AccountForm.php
index a322b09..79059af 100644
--- a/core/modules/user/src/AccountForm.php
+++ b/core/modules/user/src/AccountForm.php
@@ -46,7 +46,7 @@
    *   The entity manager.
    * @param \Drupal\Core\Language\LanguageManagerInterface $language_manager
    *   The language manager.
-   * @param \Drupal\Core\Entity\Query\QueryFactory
+   * @param \Drupal\Core\Entity\Query\QueryFactory $entity_query
    *   The entity query factory.
    */
   public function __construct(EntityManagerInterface $entity_manager, LanguageManagerInterface $language_manager, QueryFactory $entity_query) {
diff --git a/core/modules/user/src/Controller/UserController.php b/core/modules/user/src/Controller/UserController.php
index b5ce805..95f0ff4 100644
--- a/core/modules/user/src/Controller/UserController.php
+++ b/core/modules/user/src/Controller/UserController.php
@@ -164,6 +164,8 @@ public function logout() {
   }
 
   /**
+   * Menu callback; Cancel a user account via email confirmation link.
+   *
    * @todo Remove user_cancel_confirm().
    */
   public function confirmCancel(UserInterface $user, $timestamp = 0, $hashed_pass = '') {
diff --git a/core/modules/user/src/Plugin/views/field/Link.php b/core/modules/user/src/Plugin/views/field/Link.php
index b62d80e..a83d600 100644
--- a/core/modules/user/src/Plugin/views/field/Link.php
+++ b/core/modules/user/src/Plugin/views/field/Link.php
@@ -80,6 +80,7 @@ public function render(ResultRow $values) {
    * Alters the field to render a link.
    *
    * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity to render.
    * @param \Drupal\views\ResultRow $values
    *   The current row of the views result.
    *
diff --git a/core/modules/user/src/Plugin/views/wizard/Users.php b/core/modules/user/src/Plugin/views/wizard/Users.php
index 1052476..e1681c9 100644
--- a/core/modules/user/src/Plugin/views/wizard/Users.php
+++ b/core/modules/user/src/Plugin/views/wizard/Users.php
@@ -10,10 +10,6 @@
 use Drupal\views\Plugin\views\wizard\WizardPluginBase;
 
 /**
- * @todo: replace numbers with constants.
- */
-
-/**
  * Tests creating user views with the wizard.
  *
  * @ViewsWizard(
@@ -21,6 +17,8 @@
  *   base_table = "users",
  *   title = @Translation("Users")
  * )
+ *
+ * @todo: replace numbers with constants.
  */
 class Users extends WizardPluginBase {
 
diff --git a/core/modules/user/src/Tests/UserLoginTest.php b/core/modules/user/src/Tests/UserLoginTest.php
index 43202d6..4913546 100644
--- a/core/modules/user/src/Tests/UserLoginTest.php
+++ b/core/modules/user/src/Tests/UserLoginTest.php
@@ -140,11 +140,14 @@ function testPasswordRehashOnLogin() {
   /**
    * Make an unsuccessful login attempt.
    *
-   * @param $account
+   * @param \Drupal\user\Entity\User $account
    *   A user object with name and pass_raw attributes for the login attempt.
-   * @param $flood_trigger
-   *   Whether or not to expect that the flood control mechanism will be
-   *   triggered.
+   * @param mixed $flood_trigger
+   *   (optional) Whether or not to expect that the flood control mechanism will
+   *   be triggered. Defaults to NULL.
+   *   - Set to 'user' to expect a 'too many failed logins error.
+   *   - Set to any value to expect an error for too many failed logins per IP.
+   *   - Set to NULL to expect a failed login.
    */
   function assertFailedLogin($account, $flood_trigger = NULL) {
     $edit = array(
diff --git a/core/modules/user/src/UserStorageInterface.php b/core/modules/user/src/UserStorageInterface.php
index 104c4ae..afcfcfb 100644
--- a/core/modules/user/src/UserStorageInterface.php
+++ b/core/modules/user/src/UserStorageInterface.php
@@ -13,12 +13,13 @@
 /**
  * Defines an interface for user entity storage classes.
  */
-interface UserStorageInterface extends EntityStorageInterface{
+interface UserStorageInterface extends EntityStorageInterface {
 
   /**
    * Update the last login timestamp of the user.
    *
    * @param \Drupal\user\UserInterface $account
+   *   User object to change.
    */
   public function updateLastLoginTimestamp(UserInterface $account);
 
diff --git a/core/modules/user/user.module b/core/modules/user/user.module
index a251fd7..4026dc4 100644
--- a/core/modules/user/user.module
+++ b/core/modules/user/user.module
@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Enables the user registration and login system.
+ */
+
 use Drupal\Component\Utility\Crypt;
 use Drupal\Component\Utility\String;
 use Drupal\Component\Utility\Unicode;
@@ -23,11 +28,6 @@
 use Drupal\menu_link\Entity\MenuLink;
 
 /**
- * @file
- * Enables the user registration and login system.
- */
-
-/**
  * Maximum length of username text field.
  */
 const USERNAME_MAX_LENGTH = 60;
@@ -273,6 +273,7 @@ function user_load($uid, $reset = FALSE) {
  *
  * @param string $mail
  *   String with the account's email address.
+ *
  * @return object|bool
  *   A fully-loaded $user object upon successful user load or FALSE if user
  *   cannot be loaded.
@@ -289,6 +290,7 @@ 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
  *   cannot be loaded.
@@ -309,7 +311,6 @@ function user_load_by_name($name) {
  * @return string|null
  *   A translated violation message if the name is invalid or NULL if the name
  *   is valid.
- *
  */
 function user_validate_name($name) {
   $definition = BaseFieldDefinition::create('string')
@@ -400,7 +401,7 @@ function _user_role_permissions_update($roles) {
 /**
  * Checks for usernames blocked by user administration.
  *
- * @param $name
+ * @param string $name
  *   A string containing a name of the user.
  *
  * @return bool
@@ -468,7 +469,7 @@ function user_preprocess_block(&$variables) {
  * @param \Drupal\Core\Session\Interface $account
  *   The account object for the user whose name is to be formatted.
  *
- * @return
+ * @return string
  *   An unsanitized string with the username to display. The code receiving
  *   this result must ensure that \Drupal\Component\Utility\String::checkPlain()
  *   is called on it before it is printed to the page.
@@ -508,14 +509,14 @@ function user_template_preprocess_default_variables_alter(&$variables) {
  *
  * Default template: username.html.twig.
  *
- * @param array $variables
- *   An associative array containing:
- *   - account: The user account (Drupal\user\Plugin\Core\Entity\User).
- *
  * Modules that make any changes to variables like 'name' or 'extra' must ensure
  * that the final string is safe to include directly in the output by using
  * \Drupal\Component\Utility\String::checkPlain() or
  * \Drupal\Component\Utility\Xss::filter().
+ *
+ * @param array $variables
+ *   An associative array containing:
+ *   - account: The user account (Drupal\user\Plugin\Core\Entity\User).
  */
 function template_preprocess_username(&$variables) {
   $account = $variables['account'] ?: new AnonymousUserSession();
@@ -650,7 +651,7 @@ function user_user_logout($account) {
  *   - langcode: A language code to be used when generating locale-sensitive
  *    URLs. If langcode is NULL the users preferred language is used.
  *
- * @return
+ * @return string
  *   A unique URL that provides a one-time log in for the user, from which
  *   they can change their password.
  */
@@ -684,7 +685,7 @@ function user_pass_reset_url($account, $options = array()) {
  *   - langcode: A language code to be used when generating locale-sensitive
  *     URLs. If langcode is NULL the users preferred language is used.
  *
- * @return
+ * @return string
  *   A unique URL that may be used to confirm the cancellation of the user
  *   account.
  *
@@ -720,7 +721,7 @@ function user_cancel_url($account, $options = array()) {
  * @param int $login
  *   The UNIX timestamp of the user's last login.
  *
- * @return
+ * @return string
  *   A string that is safe for use in URLs and SQL statements.
  */
 function user_pass_rehash($password, $timestamp, $login) {
@@ -734,11 +735,11 @@ function user_pass_rehash($password, $timestamp, $login) {
  * Form API will invoke it, or batch_process() needs to be invoked after calling
  * this function and should define the path to redirect to.
  *
- * @param $edit
+ * @param array $edit
  *   An array of submitted form values.
- * @param $uid
+ * @param int $uid
  *   The user ID of the user account to cancel.
- * @param $method
+ * @param string $method
  *   The account cancellation method to use.
  *
  * @see _user_cancel()
@@ -906,7 +907,7 @@ function user_cancel_methods() {
 /**
  * Delete a user.
  *
- * @param $uid
+ * @param int $uid
  *   A user ID.
  */
 function user_delete($uid) {
@@ -916,7 +917,7 @@ function user_delete($uid) {
 /**
  * Delete multiple user accounts.
  *
- * @param $uids
+ * @param int[] $uids
  *   An array of user IDs.
  *
  * @see hook_ENTITY_TYPE_predelete()
@@ -939,15 +940,15 @@ function user_delete_multiple(array $uids) {
  * To theme user profiles, copy core/modules/user/templates/user.html.twig
  * to your theme directory, and edit it as instructed in that file's comments.
  *
- * @param $account
+ * @param \Drupal\Core\Entity\EntityInterface $account
  *   A user object.
- * @param $view_mode
+ * @param string $view_mode
  *   View mode, e.g. 'full'.
- * @param $langcode
+ * @param string|NULL $langcode
  *   (optional) A language code to use for rendering. Defaults to the global
  *   content language of the current request.
  *
- * @return
+ * @return array
  *   An array as expected by drupal_render().
  */
 function user_view($account, $view_mode = 'full', $langcode = NULL) {
@@ -957,15 +958,15 @@ function user_view($account, $view_mode = 'full', $langcode = NULL) {
 /**
  * Constructs a drupal_render() style array from an array of loaded users.
  *
- * @param $accounts
+ * @param \Drupal\Core\Entity\EntityInterface[] $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.'
- * @param $langcode
+ * @param string $view_mode
+ *   (optional) View mode, e.g., 'full', 'teaser'... Defaults to 'teaser'.
+ * @param string|NULL $langcode
  *   (optional) A language code to use for rendering. Defaults to the global
  *   content language of the current request.
  *
- * @return
+ * @return array
  *   An array in the format expected by drupal_render().
  */
 function user_view_multiple($accounts, $view_mode = 'full', $langcode = NULL) {
@@ -1003,17 +1004,18 @@ function user_mail($key, &$message, $params) {
  * some additional tokens that can be used in email messages generated by
  * user_mail().
  *
- * @param $replacements
+ * @param array $replacements
  *   An associative array variable containing mappings from token names to
  *   values (for use with strtr()).
- * @param $data
+ * @param array $data
  *   An associative array of token replacement values. If the 'user' element
  *   exists, it must contain a user account object with the following
  *   properties:
  *   - login: The UNIX timestamp of the user's last login.
  *   - pass: The hashed account login password.
- * @param $options
- *   Unused parameter required by \Drupal\Core\Utility\Token::replace().
+ * @param array $options
+ *   A keyed array of settings and flags to control the token replacement
+ *   process. See \Drupal\Core\Utility\Token::replace().
  */
 function user_mail_tokens(&$replacements, $data, $options) {
   if (isset($data['user'])) {
@@ -1025,17 +1027,17 @@ function user_mail_tokens(&$replacements, $data, $options) {
 /*** Administrative features ***********************************************/
 
 /**
- * Retrieve an array of roles matching specified conditions.
+ * Retrieve the names of roles matching specified conditions.
  *
- * @param $membersonly
- *   Set this to TRUE to exclude the 'anonymous' role.
- * @param $permission
- *   A string containing a permission. If set, only roles containing that
- *   permission are returned.
+ * @param bool $membersonly
+ *   (optional) Set this to TRUE to exclude the 'anonymous' role. Defaults to
+ *   FALSE.
+ * @param string|NULL $permission
+ *   (optional) A string containing a permission. If set, only roles containing
+ *   that permission are returned. Defaults to NULL, which returns all roles.
  *
- * @return
- *   An associative array with the role id as the key and the role name as
- *   value.
+ * @return array
+ *   An array of the names of the roles.
  */
 function user_role_names($membersonly = FALSE, $permission = NULL) {
   return array_map(function ($item) {
@@ -1101,14 +1103,15 @@ function user_user_role_delete(RoleInterface $role) {
 /**
  * Retrieve an array of roles matching specified conditions.
  *
- * @param $membersonly
- *   Set this to TRUE to exclude the 'anonymous' role.
- * @param $permission
- *   A string containing a permission. If set, only roles containing that
- *   permission are returned.
+ * @param bool $membersonly
+ *   (optional) Set this to TRUE to exclude the 'anonymous' role. Defaults to
+ *   FALSE.
+ * @param string|NULL $permission
+ *   (optional) A string containing a permission. If set, only roles containing
+ *   that permission are returned. Defaults to NULL, which returns all roles.
  *
- * @return
- *   An associative array with the role id as the key and the role object as
+ * @return array
+ *   An associative array with the role id as the key and the role name as
  *   value.
  */
 function user_roles($membersonly = FALSE, $permission = NULL) {
@@ -1144,10 +1147,10 @@ function user_roles($membersonly = FALSE, $permission = NULL) {
 /**
  * Fetches a user role by role ID.
  *
- * @param $rid
+ * @param string $rid
  *   A string representing the role ID.
  *
- * @return
+ * @return \Drupal\user\RoleInterface|NULL
  *   A fully-loaded role object if a role with the given ID exists, or NULL
  *   otherwise.
  *
@@ -1166,13 +1169,13 @@ function user_role_load($rid) {
  * role, the form submit handler may directly pass the submitted values for the
  * checkboxes form element to this function.
  *
- * @param $rid
+ * @param mixed $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.
+ * @param array $permissions
+ *   (optional) 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.
  *   @code
  *     array(
  *       'administer nodes' => 0,                // Revoke 'administer nodes'
@@ -1203,10 +1206,10 @@ function user_role_change_permissions($rid, array $permissions = array()) {
 /**
  * Grant permissions to a user role.
  *
- * @param $rid
+ * @param mixed $rid
  *   The ID of a user role to alter.
- * @param $permissions
- *   A list of permission names to grant.
+ * @param array $permissions
+ *   (optional) A list of permission names to grant.
  *
  * @see user_role_change_permissions()
  * @see user_role_revoke_permissions()
@@ -1223,10 +1226,10 @@ function user_role_grant_permissions($rid, array $permissions = array()) {
 /**
  * Revoke permissions from a user role.
  *
- * @param $rid
+ * @param mixed $rid
  *   The ID of a user role to alter.
- * @param $permissions
- *   A list of permission names to revoke.
+ * @param array $permissions
+ *   (optional) A list of permission names to revoke.
  *
  * @see user_role_change_permissions()
  * @see user_role_grant_permissions()
@@ -1244,10 +1247,7 @@ function user_role_revoke_permissions($rid, array $permissions = array()) {
  * Conditionally create and send a notification email when a certain
  * operation happens on the given user account.
  *
- * @see user_mail_tokens()
- * @see \Drupal\Core\Mail\MailManagerInterface::mail()
- *
- * @param $op
+ * @param string $op
  *   The operation being performed on the account. Possible values:
  *   - 'register_admin_created': Welcome message for user created by the admin.
  *   - 'register_no_approval_required': Welcome message when user
@@ -1259,19 +1259,20 @@ function user_role_revoke_permissions($rid, array $permissions = array()) {
  *   - 'status_blocked': Account blocked.
  *   - 'cancel_confirm': Account cancellation request.
  *   - 'status_canceled': Account canceled.
- *
- * @param $account
+ * @param \Drupal\Core\Session\AccountInterface $account
  *   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
+ * @param string $langcode
+ *   (optional) Language code to use for the notification, overriding account
  *   language.
  *
- * @return
- *   The return value from \Drupal::service('plugin.manager.mail')->mail(), if
- *   ends up being called.
+ * @return array
+ *   An array containint various information about the message.
+ *   See \Drupal\Core\Mail\MailManagerInterface::mail() for details.
+ *
+ * @see user_mail_tokens()
  */
-function _user_mail_notify($op, $account, $langcode = NULL) {
+function _user_mail_notify($op, AccountInterface $account, $langcode = NULL) {
   // By default, we always notify except for canceled and blocked.
   $notify = \Drupal::config('user.settings')->get('notify.' . $op);
   if ($notify || ($op != 'status_canceled' && $op != 'status_blocked')) {
@@ -1381,7 +1382,7 @@ function user_modules_uninstalled($modules) {
 /**
  * Saves visitor information as a cookie so it can be reused.
  *
- * @param $values
+ * @param array $values
  *   An array of key/value pairs to be saved into a cookie.
  */
 function user_cookie_save(array $values) {
@@ -1394,7 +1395,7 @@ function user_cookie_save(array $values) {
 /**
  * Delete a visitor information cookie.
  *
- * @param $cookie_name
+ * @param string $cookie_name
  *   A cookie name such as 'homepage'.
  */
 function user_cookie_delete($cookie_name) {