wiki:GCI/Documentation/DoxygenCleanup

Version 6 (modified by Gedare Bloom, on 09/12/18 at 19:38:39) (diff)

--

Doxygen Clean-up

The cleanup tasks consist of changes to make Doxygen use consistent with the Doxygen Recommendations. The submission consists of a patch ("diff"), and the student's name and email address for the commit message.

Directions for Students

For all tasks related to improved RTEMS "Doxygenation"; you should also read through Doxygen Recommendations.

Students will submit a patch generated by git. You can do this with a git command similar to:

$ git diff > gci-doxygen-taskXYZ.diff

Use sentences for function @brief

Convert function @brief from "Table of Contents" to "Topic sentence" style. The descriptive text of a function's @brief is used to start a paragraph, so it should be a simple, concise sentence describing the function that begins with an active, present tense verb. See Doxygen Recommendations#Declaring functions? for an example. When the description begins with a noun, rewrite the description so that the action of the function comes first. Eliminate any redundant wording such as "Function that does..." or "This function...".

Use @param to document function parameters

Replace @a with @param. See Doxygen Recommendations#Declaring functions? for an example. If you cannot determine whether a parameter is "in", "out", or "in,out" then ask for assistance.

Use @retval to document function return values

Replace @return with @retval statements. See Doxygen Recommendations#Declaring functions? for an example. If you cannot determine the possible return values for a particular function then ask for assistance.

Hierarchy formatting and correctness

There are multiple levels of groupings that RTEMS functions fall into. We want to represent this in Doxygen. To determine the subsystem (higher level grouping) that a group falls into. This task is designed to put the RTEMS Modules into a logical hierarchy.

  1. Add missing @defgroup
  2. Nest subgroups
    1. Find the @defgroup / @addtogroup
    2. Add an @ingroup indicating the "subsystem" for the @defgroup
  3. Put all @{ for @defgroup, @name statements in the same comment block as the defgroup/name statement. See Doxygen Recommendations#Using .40defgroup for group definitions? for an example.
  4. Ensure all @{ have matching @}. See Doxygen Recommendations#Ending the file? for how this should be done at the end of a header file for the primary defgroup. If you cannot determine where to place the terminator for a @defgroup or @name then ask for assistance.

Add missing @defgroup

Identify what @ingroup do not have a @defgroup, and add @defgroup for the missing ones. This task comprises searching for @ingroup labels and matching them with a @defgroup. A little bit of scripting should help, for example:

$> cd rtems/cpukit
$> grep ingroup score/include/rtems/score/thread.h
 *  @ingroup Score
$> grep -R defgroup * | grep "Score"
...
score/include/rtems/score/object.h: * @defgroup Score SuperCore
...

Would be a way to find the group definition for the Score group. If you get no results for the defgroup query, then probably the group has not been defined. If you get too many results, you can do additional filtering, for example:

$> grep -R defgroup * | grep "Score "
score/include/rtems/score/object.h: * @defgroup Score SuperCore

grep

-R means recursively look into every file

  • means every folder | means pipe the output through

grep "Score" means filter for "Score"

Use the knowledge there is a space after the group's name for the group's description to filter the results to exactly the defgroup you want to find.=== = Nest Subgroups ====

look at the subfolder in cpukit that contains the file.

  • cpukit/rtems -> Classic API
  • cpukit/posix -> POSIX API
  • cpukit/score -> SuperCore
  • cpukit/libfs -> (1) Filesystems (2) filesystem X
  • cpukit/libcsupport -> Subsystem (Higher Level Grouping) = Libc Support, keep the lower level grouping as determined from file.

Using Doxygen Subgroups

Doxygen is used to put groups into subsystems by using @defgroup or @addtogroup. The difference between @defgroup and @addtogroup is that @defgroup forces each call to be unique, while @addtogroup merges multiple groups with the same name together. For expediency and robustness of the Doxygen system for RTEMS, @addtogroup may be preferable.

To use Doxygen subgrouping add the following to the comments Example: Malloc is a subgroup of Libc Support

/

  • @defgroup Malloc malloc.h the file with the @defgroup
  • @ingroup Libc Support this is what we want to add
  • @brief Brief In Table of Contents Style* *Style depends on where the */ comment is in the file

Doxygen Grouping Example

Directions for Mentors

The student will submit a patch that should be reviewed for correctness. When correct, if the mentor doesn't have git write permission, they should post the patch to devel. If the mentor does have write permission, they are free to commit it. In either case, we need the student's name and email to give credit in the commit message.