Issue #1842528 by cferthorney, owenpm3, jhodgdon: description of hook_user_categories() is incorrect

1 files changed, 17 insertions, 1 deletions

diff --git a/modules/user/user.api.php b/modules/user/user.api.php
index e732c146a..f205a85b5 100644
--- a/modules/user/user.api.php
+++ b/modules/user/user.api.php
@@ -183,7 +183,23 @@ function hook_user_operations() {
 }
 
 /**
- * Retrieve a list of user setting or profile information categories.
+ * Define a list of user settings or profile information categories.
+ *
+ * There are two steps to using hook_user_categories():
+ * - Create the category with hook_user_categories().
+ * - Display that category on the form ID of "user_profile_form" with
+ *   hook_form_FORM_ID_alter().
+ *
+ * Step one builds out the category but it won't be visible on your form until
+ * you explicitly tell it to do so.
+ *
+ * The function in step two should contain the following code in order to
+ * display your new category:
+ * @code
+ * if ($form['#user_category'] == 'mycategory') {
+ *   // Return your form here.
+ * }
+ * @endcode
  *
  * @return
  *   An array of associative arrays. Each inner array has elements: