wiki:GCI/Documentation/DoxygenCleanup

Version 1 (modified by Gedare Bloom, on Nov 17, 2015 at 7:27:13 PM) (diff)

Import from GCI/Projects

Doxygen

Table of Contents

    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.