Topics/groups in D7 need cleanup

We could maybe have a few update groups, like "system", "node", and "miscellaneous". But having a group for each module seems rather silly, since they're already grouped on the whatever.install file page.

That would work if those three groups were defined in one file, and were never used elsewhere. If the groups were used elsewhere, you would also need to find places where it said things like:

@ingroup update_manager_update
@addtogroup update_manager_update

and change those to use group update_manager instead.

Just as a note:
This has been added as a GCI task
http://www.google-melange.com/gci/task/show/google/gci2010/drupal/t12933...

The task is currently unclaimed. blackjack48: do you intend to claim it?

h_peter: OK. You can ping me on IRC or ask questions here if you need some guidance. Thanks!

Good first pass, thanks!

A few notes/to dos:

a) Several of the added lines have spaces at the end. Please remove them. Some editors have settings that will show you spaces at ends of lines, or a function to remove those, so you might investigate in your text editor of choice.

b) I like the idea of having a few groups of update functions, and system, node, and misc makes some sense to me... but I'm not sure about how you have divided them. For instance, I don't think Block should be part of the Node group, and maybe the Field Storage SQL updates should go in "misc" and not "system". Same with Statistics. So... maybe the choice of which modules to be put in which group needs a bit of work.

c)

 /**
- * @defgroup updates-6.x-to-7.x Contact updates from 6.x to 7.x
+ * @addtogroup updates-6.x-to-7.x-misc Updates from 6.x to 7.x: miscellaneous
  * @{
+ * Miscellaneous update functions from 6.x to 7.x.
  */
 

If you are doing @addtogroup, then you shoudn't have descriptive information here. Maybe you meant to have this be @defgroup? The Node one in node.install has the same problem.

d) There are a LOT of groups in the Translation module. I wonder if they are even necessary?

e) A big chunk of documentation got cut:

@defgroup field_structs Field API data structures
...

We probably need that documentation somewhere. If it's an empty group, then we need to put the documentation somewhere else. Not sure where off-hand.

This is looking good.

We should file a separate issue on the @param in @defgroup not being displayed. That information that is now in the Field API should be presented in a different way. It is not function params, and shouldn't be using @param. It should be presented as a list... I'll file an issue shortly.

Only a couple of things I would suggest changing in the current patch:
- There is still a bit of inconsistency in which updates are assigned to which groups. For instance, the field.install updates are in system, but the field_sql_storage.install updates are in misc. I think those two should be together?
- The updates in openid.install are still in their own group (prob should be in misc)
- I think I would put the user.install updates in System not Misc too.

Thanks!

Here's the other issue:
#1011740: Wrong info presentation in Field API Structures

This version looks great to me, and the patch applies cleanly as well. Thanks!

Let's get this in, and then we can take one more look at the Topics page on api.drupal.org and make sure it is all up to standards. This should get us at least most (if not all) of the way there. Great work!

That suggestion is fine with me too, and I agree that the defgroup should be in system.install.

Looks good, thanks!

It looks like api.drupal.org has already updated with this new information. This is obviously much better than before!

But I think there is a bit more to be done:

a) A few topics have first-line descriptions that are longer than just one line, such as Batch Operations, and I think Node API Hooks (and anything else that goes longer than about 1.5 lines on http://api.drupal.org/api/drupal/groups/7).

b) Several topics have non-standard names
- "indexing Taxonomy functions maintaining {taxonomy_index}." (should start with capital letter and not end with a period, and ... what does that mean anyway?).
- "Field language API" -- language should be Language, to be consistent with the other Field API sections.
- A couple other ones end in "." too.

c) At least one description is non-standard: Menu tree (doesn't end with .). Maybe this should just be merged with the Menu System group anyway?

Actually, looking at http://api.drupal.org/api/drupal/includes--menu.inc/group/menu/7 you can see that there are 5 "subgroups" defined within the Menu group... I guess you are right that they can stay as subgroups for now.

Two minor things with this patch, which is otherwise great:

a)

 /**
- * @defgroup taxonomy indexing Taxonomy functions maintaining {taxonomy_index}.
+ * @defgroup taxonomy Taxonomy indexing

I don't think this group's machine name should be "taxonomy". It should probably be "taxonomy_index".

b)

+ * Menu item definitions provide one of these constants,
+ * which are shortcuts for combinations of

Wrap as close to 80 characters as possible. The first line is too short.

Great! Let's get this one in, and then we can take one more scan of the Topics list and make sure we are really done.

The changes seem to be up on api.drupal.org already, and I think we can call this one "fixed" this time. I'll update the GCI task appropriately. Thanks again h_peter!