Index: modules/user/user.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.module,v
retrieving revision 1.806
diff -u -p -r1.806 user.module
--- modules/user/user.module	24 Jun 2007 00:38:40 -0000	1.806
+++ modules/user/user.module	24 Jun 2007 07:30:07 -0000
@@ -87,11 +87,10 @@ function user_external_load($authname) {
  * regenerates the session, etc.
  *
  * @param $account
- *    An authenticated user object to be set as the currently logged
- *    in user.
+ *    An authenticated user object to be set as the currently logged in user.
  * @param $edit
  *    The array of form values submitted by the user, if any.
- * @return boolean
+ * @return
  *    TRUE if the login succeeds, FALSE otherwise.
  */
 function user_external_login($account, $edit = array()) {
@@ -118,7 +117,6 @@ function user_external_login($account, $
  * @param $array
  *   An associative array of attributes to search for in selecting the
  *   user, such as user name or e-mail address.
- *
  * @return
  *   A fully-loaded $user object upon successful user load or FALSE if user cannot be loaded.
  */
@@ -180,13 +178,13 @@ function user_load($array = array()) {
  * @param $account
  *   The $user object for the user to modify or add. If $user->uid is
  *   omitted, a new user will be added.
- *
  * @param $array
  *   An array of fields and values to save. For example array('name' => 'My name');
  *   Setting a field to NULL deletes it from the data column.
- *
  * @param $category
  *   (optional) The category for storing profile information in.
+ * @return
+ *   A fully-loaded $user object.
  */
 function user_save($account, $array = array(), $category = 'account') {
   // Dynamically compose a SQL query:
@@ -332,6 +330,11 @@ function user_save($account, $array = ar
 
 /**
  * Verify the syntax of the given name.
+ *
+ * @param $name
+ *   The username to validate.
+ * @return
+ *   Returns a message on error, void otherwise.
  */
 function user_validate_name($name) {
   if (!strlen($name)) return t('You must enter a username.');
@@ -414,17 +417,16 @@ function user_password($length = 10) {
 /**
  * Determine whether the user has a given privilege.
  *
+ * All permission checks in Drupal should go through this function. This
+ * way, we guarantee consistent behavior, and ensure that the superuser
+ * can perform all actions.
+ *
  * @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.
- *
  * @return
  *   boolean TRUE if the current user has the requested permission.
- *
- * All permission checks in Drupal should go through this function. This
- * way, we guarantee consistent behavior, and ensure that the superuser
- * can perform all actions.
  */
 function user_access($string, $account = NULL) {
   global $user;
@@ -460,7 +462,10 @@ function user_access($string, $account =
 /**
  * Checks for usernames blocked by user administration
  *
- * @return boolean TRUE for blocked users, FALSE for active
+ * @param $name
+ *   The username
+ * @return
+ *   TRUE for blocked users, FALSE for active
  */
 function user_is_blocked($name) {
   $deny  = db_fetch_object(db_query("SELECT name FROM {users} WHERE status = 0 AND name = LOWER('%s')", $name));
@@ -742,8 +747,13 @@ function theme_user_picture($account) {
 
 /**
  * Make a list of users.
- * @param $items an array with user objects. Should contain at least the name and uid
  *
+ * @param $items
+ *   An array with user objects. Should contain at least the name and uid
+ * @param $title
+ *   (optional) The title of the list.
+ * @return
+ *   A string containing the themed user list.
  * @ingroup themeable
  */
 function theme_user_list($users, $title = NULL) {
@@ -1004,8 +1014,12 @@ function user_current_to_arg($arg) {
 }
 
 /**
- * Accepts an user object, $account, or a DA name and returns an associative
- * array of modules and DA names. Called at external login.
+ * Given a user, aaccount, or a DA name, returns the matching modules and DA names; called at external login.
+ *
+ * @param $authname
+ *   An user object, $account, or a DA name.
+ * @return
+ *   An associative array of modules and their DA names, or 0 if no matches.
  */
 function user_get_authmaps($authname = NULL) {
   $result = db_query("SELECT authname, module FROM {authmap} WHERE authname = '%s'", $authname);
@@ -1069,6 +1083,8 @@ function user_login(&$form_state, $msg =
 }
 
 /**
+ * Retrieve the sequential list of user validate functions.
+ *
  * Setup a series for validators which check for blocked/denied users,
  * then authenticate against local database, then return an error if
  * authentication fails. Distributed authentication modules (e.g.
@@ -1081,9 +1097,9 @@ function user_login(&$form_state, $msg =
  * drupal_form_alter() in drupal.module for an example of altering
  * this series of validators.
  *
- * @return array
+ * @return
  *   A simple list of validate functions.
- **/
+ */
 function user_login_default_validators() {
   return array('user_login_name_validate', 'user_login_authenticate_validate', 'user_login_final_validate');
 }
@@ -1091,8 +1107,9 @@ function user_login_default_validators()
 /**
  * A FAPI validate handler. Sets an error is supplied username has been blocked or denied access.
  *
- * @return void
- **/
+ * @return
+ *   void
+ */
 function user_login_name_validate($form, &$form_state) {
   if (isset($form_state['values']['name'])) {
     if (user_is_blocked($form_state['values']['name'])) {
@@ -1109,9 +1126,10 @@ function user_login_name_validate($form,
 /**
  * A validate handler on the login form. Check supplied username/password against local users table.
  * If successful, sets the global $user object.
-
- * @return void
- **/
+ *
+ * @return
+ *   void
+ */
 function user_login_authenticate_validate($form, &$form_state) {
   user_authenticate($form_state['values']['name'], trim($form_state['values']['pass']));
 }
@@ -1120,8 +1138,9 @@ function user_login_authenticate_validat
  * A validate handler on the login form. Should be the last validator. Sets an error if
  * user has not been authenticated yet.
  *
- * @return void
- **/
+ * @return
+ *   void
+ */
 function user_login_final_validate($form, &$form_state) {
   global $user;
   if (!$user->uid) {
@@ -1135,7 +1154,7 @@ function user_login_final_validate($form
  *
  * @return
  *   A $user object, if successful.
- **/
+ */
 function user_authenticate($name, $pass) {
   global $user;
 
@@ -1148,8 +1167,9 @@ function user_authenticate($name, $pass)
 /**
  * A validate handler on the login form. Update user's login timestamp, fire hook_user('login), and generate new session ID.
  *
- * @return void
- **/
+ * @return
+ *   void
+ */
 function user_login_submit($form, &$form_state) {
   global $user;
   if ($user->uid) {
@@ -1170,8 +1190,9 @@ function user_login_submit($form, &$form
  * Helper function for authentication modules. Either login in or registers the current user, based on username.
  * Either way, the global $user object is populated based on $name.
  *
- * @return void
- **/
+ * @return
+ *   void
+ */
 function user_external_login_register($name, $module) {
   global $user;
 
@@ -1633,8 +1654,12 @@ function user_confirm_delete($name, $uid
 /**
  * Delete a user.
  *
- * @param $edit An array of submitted form values.
- * @param $uid The user ID of the user to delete.
+ * @param $edit
+ *   An array of submitted form values.
+ * @param $uid
+ *   The user ID of the user to delete.
+ * @return
+ *   void
  */
 function user_delete($edit, $uid) {
   $account = user_load(array('uid' => $uid));
@@ -1691,7 +1716,6 @@ function user_view($account) {
  *
  * @param $account
  *   A user object.
- *
  * @return
  *   A structured array containing the individual elements of the profile.
  */
@@ -1943,7 +1967,6 @@ function user_admin_access() {
  *   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.
- *
  * @return
  *   An associative array with the role id as the key and the role name as value.
  */
@@ -3086,12 +3109,12 @@ function theme_user_signature($signature
  * Return an array of token to value mappings for user e-mail messages.
  *
  * @param $account
- *  The user object of the account being notified.  Must contain at
- *  least the fields 'uid', 'name', and 'mail'.
+ *   The user object of the account being notified.  Must contain at
+ *   least the fields 'uid', 'name', and 'mail'.
  * @param $password
- *  Optional string containing the user's current password (if known).
+ *   Optional string containing the user's current password (if known).
  * @return
- *  Array of mappings from token names to values (for use with strtr()).
+ *   Array of mappings from token names to values (for use with strtr()).
  */
 function user_mail_tokens($account, $password = NULL) {
   global $base_url;
@@ -3120,24 +3143,21 @@ function user_mail_tokens($account, $pas
  * @see drupal_mail()
  *
  * @param $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 self-registers
- *  'register_pending_approval': Welcome message, user pending admin approval
- *  'password_reset': Password recovery request
- *  'status_activated': Account activated
- *  'status_blocked': Account blocked
- *  'status_deleted': Account deleted
- *
+ *   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 self-registers
+ *   'register_pending_approval': Welcome message, user pending admin approval
+ *   'password_reset': Password recovery request
+ *   'status_activated': Account activated
+ *   'status_blocked': Account blocked
+ *   'status_deleted': Account deleted
  * @param $account
- *  The user object of the account being notified.  Must contain at
- *  least the fields 'uid', 'name', and 'mail'.
- *
+ *   The user object of the account being notified.  Must contain at
+ *   least the fields 'uid', 'name', and 'mail'.
  * @param $password
- *  Optional string containing the user's current password (if known).
- *
+ *   Optional string containing the user's current password (if known).
  * @return
- *  The return value from drupal_mail(), if ends up being called.
+ *   The return value from drupal_mail(), if ends up being called.
  */
 function _user_mail_notify($op, $account, $password = NULL) {
   $mail_id = 'user-'. strtr($op, '_', '-');