Index: modules/user/user.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.api.php,v
retrieving revision 1.1
diff -u -r1.1 user.api.php
--- modules/user/user.api.php	25 Nov 2008 02:37:33 -0000	1.1
+++ modules/user/user.api.php	4 Jan 2009 20:00:41 -0000
@@ -12,41 +12,62 @@
  */
 
 /**
- * Act on user account actions.
+ * The user object has been updated and changed. Use this if
+ *  (probably along with 'insert') you want to reuse some information from the user object.
  *
- * This hook allows modules to react when operations are performed on user
- * accounts.
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ *
+ * @return
+ *   None.
+ */
+function hook_user_after_update(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * A set of user information categories is requested.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ *
+ * @return
+ *    A linear array of associative arrays. These arrays have
+ *    keys:
+ *    - "name": The internal name of the category.
+ *    - "title": The human-readable, localized name of the category.
+ *    - "weight": An integer specifying the category's sort ordering.
+ */
+function hook_user_categories(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account is being deleted. The module should remove its
+ * custom additions to the user object from the database.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_delete(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account edit form is about to be displayed. The module
+ * should present the form elements it wishes to inject into the form.
  *
- * @param $op
- *   What kind of action is being performed. Possible values (in alphabetical order):
- *   - "after_update": The user object has been updated and changed. Use this if
- *     (probably along with 'insert') if you want to reuse some information from
- *     the user object.
- *   - "categories": A set of user information categories is requested.
- *   - "delete": The user account is being deleted. The module should remove its
- *     custom additions to the user object from the database.
- *   - "form": The user account edit form is about to be displayed. The module
- *     should present the form elements it wishes to inject into the form.
- *   - "insert": The user account is being added. The module should save its
- *     custom additions to the user object into the database and set the saved
- *     fields to NULL in $edit.
- *   - "load": The user account is being loaded. The module may respond to this
- *   - "login": The user just logged in.
- *   - "logout": The user just logged out.
- *     and insert additional information into the user object.
- *   - "register": The user account registration form is about to be displayed.
- *     The module should present the form elements it wishes to inject into the
- *     form.
- *   - "submit": Modify the account before it gets saved.
- *   - "update": The user account is being changed. The module should save its
- *     custom additions to the user object into the database and set the saved
- *     fields to NULL in $edit.
- *   - "validate": The user account is about to be modified. The module should
- *     validate its custom additions to the user object, registering errors as
- *     necessary.
- *   - "view": The user's account information is being displayed. The module
- *     should format its custom additions for display and add them to the
- *     $account->content array.
  * @param &$edit
  *   The array of form values submitted by the user.
  * @param &$account
@@ -54,37 +75,153 @@
  * @param $category
  *   The active category of user information being edited.
  * @return
- *   This varies depending on the operation.
- *   - "categories": A linear array of associative arrays. These arrays have
- *     keys:
- *     - "name": The internal name of the category.
- *     - "title": The human-readable, localized name of the category.
- *     - "weight": An integer specifying the category's sort ordering.
- *   - "delete": None.
- *   - "form", "register": A $form array containing the form elements to display.
- *   - "insert": None.
- *   - "load": None.
- *   - "login": None.
- *   - "logout": None.
- *   - "submit": None:
- *   - "update": None.
- *   - "validate": None.
- *   - "view": None. For an example see: user_user().
- */
-function hook_user($op, &$edit, &$account, $category = NULL) {
-  if ($op == 'form' && $category == 'account') {
-    $form['comment_settings'] = array(
-      '#type' => 'fieldset',
-      '#title' => t('Comment settings'),
-      '#collapsible' => TRUE,
-      '#weight' => 4);
-    $form['comment_settings']['signature'] = array(
-      '#type' => 'textarea',
-      '#title' => t('Signature'),
-      '#default_value' => $edit['signature'],
-      '#description' => t('Your signature will be publicly displayed at the end of your comments.'));
-    return $form;
-  }
+ *   None.
+ */
+function hook_user_form(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account is being added. The module should save its
+ * custom additions to the user object into the database and set the saved
+ * fields to NULL in $edit.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_insert(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account is being loaded. The module may respond to this.
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_load(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user just logged in.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_login(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user just logged out.
+ * and insert additional information into the user object.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_logout(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account registration form is about to be displayed.
+ * The module should present the form elements it wishes to inject into the
+ * form.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_register(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * Modify the account before it gets saved.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_submit(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account is being changed. The module should save its
+ * custom additions to the user object into the database and set the saved
+ * fields to NULL in $edit.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_update(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user account is about to be modified. The module should
+ * validate its custom additions to the user object, registering errors as necessary.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_validate(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user's account information is being displayed. The module
+ * should format its custom additions for display and add them to the
+ * $account->content array.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param &$account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   None.
+ */
+function hook_user_view(&$edit, &$account, $category = NULL) {
 }
 
 /**