Clarification on Doxygen formatting conventions [#422084]

Doxygen formatting conventions page sets some standards for API documentation, but I've a few clarification questions about the generally accepted conventions:

1. Some core functions include @param and @return directives for functions with no parameters or return values in the following varieties:

 * @param None.

 * @return
 *   None.

Should all functions include these empty directives or should they be removed?
(See http://api.drupal.org/api/file/modules/system/system.api.php/7/source for plenty of examples.)

2. Should @see (or any other) directive be used in the description as in the following example?
(http://api.drupal.org/api/function/hook_mail/7)

 * Prepare a message based on parameters. @see drupal_mail for more.

3. Is there a strict order for @param, @return, @see, and @ingroup directives?
Most docs have @param and @return grouped together (see hook_theme in system.api.php for an example of a blank line separating the two groups of directives) followed by @see directives followed by @ingroup directives. Should a blank line separate the @param/@return directives with the @see/@ingroup directives? Should a blank line separate the @see and @ingroup directives? Which of the following is correct:

 * @param $variable
 *   Some variable description that goes on and on
 * @return $value
 *   Some return value description that goes on and on
 * @see some_function1()
 * @see some_function2()
 * @ingroup some_group1
 * @ingroup some_group2

 * @param $variable
 *   Some variable description that goes on and on
 * @return $value
 *   Some return value description that goes on and on
 *
 * @see some_function1()
 * @see some_function2()
 * @ingroup some_group1
 * @ingroup some_group2

 * @param $variable
 *   Some variable description that goes on and on
 * @return $value
 *   Some return value description that goes on and on
 *
 * @see some_function1()
 * @see some_function2()
 *
 * @ingroup some_group1
 * @ingroup some_group2

4. Are paragraphs allowed to interject between groups of @param, @return, @see, and @ingroup directives? Or should all paragraphs precede the directives?

http://api.drupal.org/api/file/modules/search/search.api.php/7/source has a couple of paragraphs that separates the @return and @ingroup directives. (Ignore some of the inconsistencies in the hook_search documentation. They're being fixed by #411388: Documentation for hook_search is missing op 'admin'.)

Comments

Comment #1

JamesAn commented 2 April 2009 at 20:14

Status:

Active

» Postponed

It was recommended by webchick to discuss these questions over at the Coding standards and best practices gdo. Go to Clarification on Doxygen formatting conventions.

Comment #2

sun

German

Karlsruhe

commented 2 April 2009 at 21:10

Status:

Postponed

» Active

Not much to discuss here.

1) For documentation of hooks it makes sense to document the @return value. However, @param None. is completely wrong; if a function takes an argument, the argument is documented with @param.

2) #178629: Properly use @see contains a very granular definition of how @see can and must be used.

3) Technically, the order is unimportant. However, @param and @return always appear in this order. @see can appear within, directly below the description, and/or below @param/@return, i.e. it appears where it makes sense regarding context. @ingroup comes last. In general, a blank line between all directive groups helps in readability.

4) Additional description can be used where it makes sense. The given example of hook_search() is very good: The "leading" description is about general usage of the hook, stuff you want to read first and you should know when using the hook. At the end, some clarifications about the example code are provided, so this part of the description has a different context and primarily serves to explain the example, not the hook.

Comment #3

dave reid

he/him

English

Nebraska USA

commented 3 April 2009 at 16:04

Mostly agreed with sun.
1. It makes sense for hook documentation, but not for any other functions.
2. Sun has said it all.
3. The standard I've seen the most and seems to make the most sense is:

 * @param $param
 *   Parameter description.
 * @retun
 *   Return value description.
 *
 * @see function1()
 * @see function2()
 *
 * @ingroup forms
 * @ingroup themable
 */