wiki:GCI/Documentation/DoxygenCleanup

Version 4 (modified by Gedare Bloom, on 09/12/18 at 19:30:14) (diff)

--

Doxygen

Table of Contents

    Doxygen

    Add Doxygen File Headers

    Given a first pass of which files we would like to improve Doxygen in, there are at least 55 tasks in this category assuming 10 files per GCI task.

    Tasks related to improved RTEMS "Doxygenation"; you should also read through Doxygen Recommendations.

    Special thanks to Gedare Bloom, Jennifer Averett, and Sebastian Huber for instructions on writing and checking Doxygen comments. The RTEMS source base has been in a long process to use Doxygen. But since Doxygen is newer than RTEMS, there are still lots of files which don't have the bare minimum of even a proper Doxygen file header comment block. These tasks consist of editing a set of files to provide a proper Doxygen style file header comment block to RTEMS source files, and merging any comments that precede any method declaration in the .c file into the Doxygen comment block preceding the method's prototype in the approriate .h file.

    Check out the Doxygen Recommendations for BSPs page for a detailed guide useful in completing these tasks.

    This task is a little tricky: there are two desired header formats:

    1. The top of the file has an @file, @ingroup, and @brief
    2. The middle of the file has an @ingroup and @brief

    The format of the @brief is different for the top of the file and the end of the file.

    Directions

    1. locate the .h file for a .c file
    2. Add the headers
    3. Check your work
    4. Continue to check your work until you're ready to submit
    5. Format the patch
    6. Submit your work
    Locating the .h file for a .c File

    Identifying the group a function is in is one of the key points of having Doxygen headers. To identify which group a function is in, locate the .h file where the function is, and use the group defined in the @defgroup tag. For example, for cpukis/score/src/watchdoginsert.c, the @ingroup would be based on this line from cpukit/score/include/rtems/score/watchdog.h:

    Identifying the Group
    /* @file                                                cpukit/example/include/example.h
     * @defgroup ScoreWatchdog Watchdog Handler
    

    The tag above defines the handle ScoreWatchdog and says it has the printable name Watchdog Handler. Thus cpukit/score/src/watchdog.c would use

    cpukit/example.c

    /* @file only used for the first header in a file

    • @ingroup ScoreWatchdog
    Locating the File

    To locate the .h file where the @defgroup (for the @ingroup) is, you can use grep as follows:

    cd rtems/cpukit/DIRECTORY
    grep -r rtems\_random\_function include
    

    DIRECTORY should be replaced with the appropriate subdirectory based on the file being edited. For the first tasks of this type, this will be score, rtems, sapi, or posix.

    Notes
    • If you locate the prototype for the method in the RTEMS source, then merge the comments in the .c file into the appropriate .h file. Please put the the comments from the .c file to the .h file Doxygen comment block above the function.
    • If you do not find the function in a .h, do NOT remove the comments above the function in the .c file. Edit any existing comments to turn them into proper Doxygen comments. Some functions in the cpukit/posix/src or cpukit/libcsupport directories are prototyped by the C library, so you may not find their prototypes.
    • Examples: The methods in cpukit/rtems/include/rtems/rtems/event.h provide a good example of how RTEMS uses Doxygen. When in doubt, there is online documentation for Doxygen at http://www.doxygen.org and you can always ask questions via the Google Code In site or in #rtems on IRC freenode.
    Add the Headers

    Once the @ingroup is found, the next step is to add the headers. For each file, there are two types of headers. The first header has an @file, an @ingroup and a Table of Contents @brief. The other headers DO NOT have an @file, but DO have an @ingroup and a Topic Sentence @brief. Please see the examples.

    First Header in a File

    Desired Format (at the top of the file):

    line 1                                                cpukit/example/example.c
    /**
     * @file
     *
     * @ingroup GROUP_FROM_dot_h_FILE
     * @brief Brief Description for Table of Contents
     */
    
    /*
     * COPYRIGHT
     * 
     * The copyright should exist in every file already, but the header will have 
     * to be edited and the copyright remain below and in a separate comment block.
     */
    

    Advice on first header in file @brief contents: The @brief text for classes and files is what will show up in a Table of Contents. The key is short, English suitable for Table of Contents. For a file with a single method, it might be the method's name in English. For example: The file with the _Chain_Initialize() method should use something like "Initialize a Chain" for the @brief text. In many cases, the .h file with this method prototyped will have an @brief which is suitable for use. In other words, you can use the @brief text from the .h file description of the same method. See above for instructions on locating the appropriate .h file. Some guidelines:

    • The first header's @brief text for classes and files will show up in Table of Contents. Use capitalization like section or chapter headings
    • Do not end the first header's @brief with a period
    Other Comments in a File

    Desired Format (in the middle of the file):

        ...                                              cpukit/example/example.c
        rtems_random_call();
        return 55;
    }
    line 10+
    /**
     * @ingroup GROUP_FROM_dot_h_FILE
     * @brief Topic sentence describing a function, if it goes over 79
     * characters, please put on the next line.
     */
    
    • Other header's @brief text for classes and files will show up in Function Descriptions. Use a topic sentence structure.
    • End the other header's @brief with a period
    Notes

    Make sure there are no tab characters embedded in the changes. RTEMS does not embed the tab character. Check your editor setting and look for one that inserts spaces and not tab characters. The tab default size is 2.

    Checking Your Work (How to Run Doxygen)

    One way to quickly become a quality coder is to make sure your code does what it's supposed to. This code is used to generate cross-references needed for certifying RTEMS in safety critical applications, as well as, telling our users (such as embedded software developers working for car manufacturers and aerospace corporations) what each function does. There are several ways to see what html is produced by the Doxygen comments written.

    Advice: please just use ONE method.

    Method 1 Calling Doxygen Directly
    1. Install doxygen
    2. Get the Doxyfile
      1. Copy the File:Doxyfile.diff? to a directory outside of the RTEMS directory.
      2. Rename Doxyfile.diff to Doxyfile.tar.gz
      3. Extract it outside the RTEMS directory
      4. Open the Doxyfile in a text editor and edit line 577 to point it at the directory you want to generate documentation for, as well as lines 28 and 41 to rename the resulting folder
    3. call doxygen from the rtems directory ~/rtems> doxygen ../Doxyfile ~/rtems> firefox cpukit_doxy/html/index.html
    4. Click on Modules
    5. Click on your module
    6. ctrl+f Function Documentation

    Once you're done looking, delete the cpukit_doxy

    ~/rtems> rm -rf cpukit_doxy
    
    Method 2 Using the do_doxygen script

    UPDATED: There is a newer do_doxygen script available at https://github.com/joelsherrill/gci_tasks/blob/master/2013/doxygen_c_header_tasks/validate/do_doxygen. Your environment needs to have the root directory of rtems set in the variable r so that $r prints the path to rtems, and the script takes as argument a relative directory from there to generate the doxygen, for example to generate the doxygen for all of libbsp you would do:

    export r=~/rtems
    ./do_doxygen c/src/lib/libbsp
    

    And it should just work.

    Outdated: There is a shell script do_doxygen in the same ftp directory as the list of files to edit http://rtems.org/ftp/pub/rtems/people/joel/Doxygen_Tasks/. It assumes the directory layout in the RTEMS Virtual Machine. There is another shell script in that directory named build_doxygen which takes command line arguments.

    Format the Patch (How to Run Doxygen)

    Please submit a patch generated by git.

    Please select a suitable name by replacing "gci-doxygen-task2.diff" with something that relates to your task. You can add an extra '-2' to the name, for example "gci-doxygen-task2-2.diff" if you need to submit more than one diff as a result of reviews.

    You can do this with a git command similar to:

    $ git diff > gci-doxygen-task2.diff
    

    Directions for RTEMS Mentors

    Task Count: Across 4 directories, a search indicates there are ~800 files with this problem. If students are given a set of 10 files, then there are ~80 of these tasks. This task can be expanded to include other directories.

    What to Submit: The student will be editing the comments in RTEMS source code and submitting a patch. Git instructions for RTEMS are at http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository#GIT_Access_for_users, and http://wiki.rtems.org/wiki/index.php/Git_Users. If there is a need for simpler instructions geared to GCI, a mentor will create them.

    Mentor Guidelines: The student will submit a patch which will likely need to be directly emailed to a mentor for review. This is necessary because the rtems-devel mailing list only accepts email from subscribers and students are not expected to subscribe. The mentor will review the patch for correctness. When correct, if the mentor doesn't have git write permission, they should post the patch to rtems-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.

    Cleanup Doxygen

    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.

    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

    Mentor Guidelines

    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 rtems-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.