Index: modules/user/user.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.api.php,v
retrieving revision 1.7
diff -u -r1.7 user.api.php
--- modules/user/user.api.php	15 Jun 2009 19:21:54 -0000	1.7
+++ modules/user/user.api.php	22 Jun 2009 15:41:52 -0000
@@ -12,39 +12,8 @@
  */
 
 /**
- * Act on user account actions.
+ * Act on when a user account is being edited.
  *
- * This hook allows modules to react when operations are performed on user
- * accounts.
- *
- * @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.
- *   - "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
- *     and insert additional information into the user object.
- *   - "login": The user just logged in.
- *   - "logout": The user just logged out.
- *   - "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
@@ -52,24 +21,9 @@
  * @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().
+ *   A $form array containing the form elements to display.
  */
-function hook_user($op, &$edit, &$account, $category = NULL) {
+function hook_user_form(&$edit, &$account, $category = NULL) {
   if ($op == 'form' && $category == 'account') {
     $form['comment_settings'] = array(
       '#type' => 'fieldset',
@@ -84,6 +38,145 @@
     return $form;
   }
 }
+
+/**
+ * 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 just logged in.
+ *
+ * The module may respond to this 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_login(&$edit, &$account, $category = NULL) {
+}
+
+/**
+ * The user just logged out.
+ *
+ * @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) {
+}
+
 /**
  * Act on user objects when loaded from the database.
  *