description of hook_user_categories() is incorrect

Yes, sounds like a good thing to fix! Apparently this mess has finally been eliminated in Drupal 8, so this is a D7 issue only unless we want to apply the fix to hook_user() in D6 as well.

Patch attached. This is my first API patch, so I hope i have done this correctly.

Patch looks fine, make sure you set the status to needs review when attaching a patch that needs review.

Thanks for the patch!

For hook documentation, the first line should be "Define..." not "Defines":
http://drupal.org/node/1354#hooks

Adjusted and resubmitted

Looks good!

Did you notice comment #1 on this issue though? A request was made that we should say something in this hook documentation about what else a module would need to do after implementing this hook... maybe we should do that?

#7: description_of_hook_user_categories_is_incorrect-1842528-7.patch queued for re-testing.

See #8.

Having read the Documentation standards for code examples [api.drupal.org], I hope this is right. I wasn't 100% certain if the @code/@endcode went before or after the @return code. But please see attached patch and let me know if I need to reorganize it.

Forgot to set status as 'needs review'

The syntax is fine (except that you need a blank line after the @endcode and before the @return).

But I don't think this gives accurate information as suggested in #1. The idea is that:
a) First you implement the hook we're documenting here, hook_user_categories().
b) Then you need to implement hook_form_FORM_ID_alter for the form ID 'user_profile_form'.
c) In that function, the given code snippet needs to be placed so that you are adding some form elements to the user profile form for your category.

I just came across this, while trying to register a sub-page user/%/edit/something using regular hook_menu(), and being confused what hook_user_categories() is doing there.

Maybe we should also document how you can disable the feature altogether, e.g. with hook_menu_alter() to change the user/%/edit/account wildcard loader?

If you want to do something that works generically for all entity types, then this "feature" is in the way.

How does this look?

/**
 * Define a list of user settings or profile information categories.
 *
 * There are two steps to using hook_user_categories().
 *	1: Create the category with hook_user_categories()
 *	2: 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
 *

Thanks for reviving this issue! Accuracy-wise, the patch looks fine. There are several formatting problems though:

1. +++ b/modules/user/user.api.php
   @@ -183,7 +183,20 @@ function hook_user_operations() {
   + *	1: Create the category with hook_user_categories()
   + *	2: Display that category on the form ID of "user_profile_form" with hook_form_FORM_ID_alter()
   

   This will not format correctly in the API documentation parser. Use a bullet list instead. See
   https://www.drupal.org/node/1354#lists
   for formatting information.

2. Do not use tabs.
3. There are trailing spaces in a couple of places in your patch at the ends of lines. Remove those. Most code editors have a setting to either highlight or remove them.
4. No documentation line should go past 80 characters.
5. If you want to make a new paragraph, you need to leave a blank line. If you do not want to make a new paragraph, sentences should be wrapped together at close-to-80-character lines.

6. +++ b/modules/user/user.api.php
   @@ -183,7 +183,20 @@ function hook_user_operations() {
   + * The function in step two should contain the following code in order to display your new category.
   + * ¶
   + * @code
   

   End the first line in : and eliminate the blank line.

7. +++ b/modules/user/user.api.php
   @@ -183,7 +183,20 @@ function hook_user_operations() {
   + *   if ($form['#user_category'] == 'mycategory') {
   + *     // Return your form here.
   + *   }
   + * @endcode
   

   This will take up less space if you do not indent the code by 2 spaces.

I believe I corrected the formatting issues.

1. Changed ordered list to bulleted list as per the API documentation
2. Removed tabs
3. Removed trailing spaces
4. Collapsed lines over 80 characters
5. Updated the paragraph to enclose the code snippet
6. Removed indents

Let me know if I've missed anything. And thank you for the feedback.

Great, nearly perfect! Just a couple of very minor things to fix and I think this will be good to go:

1. +++ b/modules/user/user.api.php
   @@ -183,7 +183,23 @@ function hook_user_operations() {
   + * There are two steps to using hook_user_categories().
   

   End this line (before the list) in :

2. +++ b/modules/user/user.api.php
   @@ -183,7 +183,23 @@ function hook_user_operations() {
   + * - Create the category with hook_user_categories()
   

   End this in .

3. +++ b/modules/user/user.api.php
   @@ -183,7 +183,23 @@ function hook_user_operations() {
   + *   hook_form_FORM_ID_alter()
   

   End this line in .

Sweet. Patch has been updated.

Looks good!

For next time - it's nice when you upload a new patch to (a) set issue to Needs Review and (b) provide an interdiff file. No worries this time. Thanks!

Committed to 7.x - thanks!