1 files changed, 38 insertions, 1 deletions
diff --git a/modules/user/user.module b/modules/user/user.module
index 84430b2f7..044ad4698 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -74,10 +74,26 @@ function user_help($path, $arg) {
 }
 
 /**
- * Invokes hook_user() in every module.
+ * Invokes a user hook in every module.
  *
  * 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:
+ *   - cancel: Invokes hook_user_cancel().
+ *   - insert: Invokes hook_user_insert().
+ *   - login: Invokes hook_user_login().
+ *   - presave: Invokes hook_user_presave().
+ *   - update: Invokes hook_user_update().
+ * @param $edit
+ *   An associative array variable containing form values to be passed
+ *   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.
+ * @param $category
+ *   The category of user information being acted upon.
  */
 function user_module_invoke($type, &$edit, $account, $category = NULL) {
   foreach (module_implements('user_' . $type) as $module) {
@@ -2287,6 +2303,27 @@ function user_cancel_url($account) {
   return url("user/$account->uid/cancel/confirm/$timestamp/" . user_pass_rehash($account->pass, $timestamp, $account->login), array('absolute' => TRUE));
 }
 
+/**
+ * Creates a unique hash value for use in time-dependent per-user URLs.
+ *
+ * This hash is normally used to build a unique and secure URL that is sent to
+ * 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().
+ *
+ * @param $password
+ *   The hashed user account password value.
+ * @param $timestamp
+ *   A unix timestamp.
+ * @param $login
+ *   The user account login name.
+ *
+ * @return
+ *   A string that is safe for use in URLs and SQL statements.
+ */
 function user_pass_rehash($password, $timestamp, $login) {
   return drupal_hmac_base64($timestamp . $login, drupal_get_hash_salt() . $password);
 }