Menu constants doc not formatted right and @name misues

I see what you mean. This appears to be a bug in the API module, since as far as I can tell the documentation is marked up correctly.

Both
http://api.drupal.org/api/drupal/includes--theme.inc/6
and
http://api.drupal.org/api/drupal/includes--theme.inc
have this problem. If you scroll down to the Constants section at the bottom, the one-line descriptions are not what you'd expect from looking at the source.

Hm.
Actually, when I go to those links, sometimes the descriptions are fine and sometimes they are not. So if they look good to you, refresh the page a few times. Here's a screen shot from the 6.x page as an illustration of what it looks like when it's not working.

Looks to me like theme.inc in D6 doesn't define those constants in comments at all:

<?php
/**
 * @name Content markers
 * @{
 * Markers used by theme_mark() and node_mark() to designate content.
 * @see theme_mark(), node_mark()
 */
define('MARK_READ',    0);
define('MARK_NEW',     1);
define('MARK_UPDATED', 2);
/**
 * @} End of "Content markers".
 */
?>

Whereas, in D7, each constant gets a comment:

<?php
/**
 * @defgroup content_flags Content markers
 * @{
 * Markers used by theme_mark() and node_mark() to designate content.
 * @see theme_mark(), node_mark()
 */

/**
 * Mark content as read.
 */
define('MARK_READ', 0);

/**
 * Mark content as being new.
 */
define('MARK_NEW', 1);

/**
 * Mark content as being updated.
 */
define('MARK_UPDATED', 2);

/**
 * @} End of "Content markers".
 */
?>

This latter version is parsed and displayed properly.

In the D6 version of theme.inc, MARK_READ has "@name Content markers" as its description because @name isn't actually a special directive, and MARK_READ is the first one in the list that follows the comment.

I'm not sure if this change is allowed for D6, but here's a patch that adds individual comments (and changes @name to @defgroup.

Looks like @name actually shows up at least 10 times in comments in D6 core, (and more in contrib,) and none of these become topics on the API site.

Am I missing something? I don't see anything referring to this directive in the Doxygen and comment formatting conventions documentation... and @name isn't used in D7 comments.

RE #2 - weird. I was sure I looked at the theme.inc source (by clicking on "view source" on api.drupal.org) in D6 and saw those definitions being correct. My mistake! So this is not an API bug after all.

The patch in #2 above is fine. And @name is not supposed to be used in Doxygen -- the API module doesn't support it. I guess we fixed this in d7 and didn't go back and fix it in d6. Do you want to make a more extensive patch that removes @name in all of d6, since it's only 10 places apparently?

Changed all @names to @defgroups, using the same machine names as D7.

Also followed D7's lead here to ensure that these @defgroups' comments start with a one-liner, for the topics page, (D7's topics page is quite a bit neater...)

You need to name patch files without the -D6 so they get tested please. At least now that rfay has fixed the d6 testing so it will work. :)

Regarding that patch:

a)

- * @name Menu item types
+ * @defgroup menu_item_types Menu item types
  * @{
+ * Definitions for various menu types.
+ *

various menu types => various menu item types

b)

 /**
- * @name Pager pieces
+ * @defgroup pagerpieces Pager pieces
  * @{
- * Use these pieces to construct your own custom pagers in your theme. Note that
- * you should NOT modify this file to customize your pager.
+ * Use these pieces to construct your own custom pagers in your theme.
+ *
+ * Note that you should NOT modify this file to customize your pager.
  */

First line should not be a command but a description.

c)

  */
 
+
 /**

Not sure why we need an extra blank line there? I think the Drupal coding standard is one blank line between functions?

Thanks jhodgdon; I've updated the patch with these changes.

Note that suggestions a) and b) from #6 will need to be changed in D7/D8 as well, since that's where the text in my patch came from. Per IRC discussion w/ jhodgdon, I'll open up a new issue for that.

Issue #1110064: two @defgroup comment fixes applies changes a) and b) to D7.

This looks good, thanks! The d7/8 patch is currently RTBC, so I expect it will be committed shortly. So this one is good to go for D6.

Thanks, committed, pushed.