Changes between Version 4 and Version 5 of GCI/Documentation/DoxygenCleanup


Ignore:
Timestamp:
Sep 12, 2018, 7:34:38 PM (9 months ago)
Author:
Gedare Bloom
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GCI/Documentation/DoxygenCleanup

    v4 v5  
    66== Doxygen ==
    77
    8 === Add Doxygen File Headers ===
    9 
    10 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.
    11 
    12 Tasks related to improved RTEMS "Doxygenation"; you should also read through [wiki:Developer/Coding/Doxygen Doxygen Recommendations].
    13 
    14 Special thanks to Gedare Bloom, Jennifer Averett, and Sebastian Huber for instructions on writing and checking Doxygen comments.
    15 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.
    16 
    17 Check out the [wiki:Developer/Coding/Doxygen_for_BSPs Doxygen Recommendations for BSPs] page for a detailed guide useful in completing these tasks.
    18 
    19 This task is a little tricky: there are two desired header formats:
    20 1. The top of the file has an @file, @ingroup, and @brief
    21 1. The middle of the file has an @ingroup and @brief
    22 The format of the @brief is different for the top of the file and the end of the file.
    23 
    24 ====  Directions  ====
    25 
    26 1. locate the .h file for a .c file
    27 1. Add the headers
    28 1. Check your work
    29 1. Continue to check your work until you're ready to submit
    30 1. Format the patch
    31 1. Submit your work
    32 =====  Locating the .h file for a .c File  =====
    33 
    34 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'':
    35 ===== Identifying the Group  =====
    36 
    37 {{{
    38 /* @file                                                cpukit/example/include/example.h
    39  * @defgroup ScoreWatchdog Watchdog Handler
    40 }}}
    41 The tag above defines the handle ''!ScoreWatchdog'' and says it has the printable name ''Watchdog Handler''. Thus ''cpukit/score/src/watchdog.c'' would use
    42                                                          cpukit/example.c
    43  /* @file // only used for the first header in a file
    44   * @ingroup !ScoreWatchdog
    45 =====  Locating the File  =====
    46 
    47 To locate the .h file where the @defgroup (for the @ingroup) is, you can use ''grep'' as follows:
    48 {{{
    49 cd rtems/cpukit/DIRECTORY
    50 grep -r rtems\_random\_function include
    51 }}}
    52 
    53 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''.
    54 =====  Notes  =====
    55 
    56  *  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.
    57 
    58  *  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.
    59 
    60  *  '''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.
    61 =====  Add the Headers  =====
    62 
    63 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.
    64 =====  First Header in a File  =====
    65 
    66 '''Desired Format''' ''(at the top of the file)'':
    67 {{{
    68 line 1                                                cpukit/example/example.c
    69 /**
    70  * @file
    71  *
    72  * @ingroup GROUP_FROM_dot_h_FILE
    73  * @brief Brief Description for Table of Contents
    74  */
    75 
    76 /*
    77  * COPYRIGHT
    78  *
    79  * The copyright should exist in every file already, but the header will have
    80  * to be edited and the copyright remain below and in a separate comment block.
    81  */
    82 }}}
    83 ''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:
    84 
    85  *  The first header's @brief text for classes and files will show up in Table of Contents. Use capitalization like section or chapter headings
    86  *  Do not end the first header's @brief with a period
    87 =====  Other Comments in a File  =====
    88 
    89 '''Desired Format''' ''(in the middle of the file)'':
    90 {{{
    91     ...                                              cpukit/example/example.c
    92     rtems_random_call();
    93     return 55;
    94 }
    95 line 10+
    96 /**
    97  * @ingroup GROUP_FROM_dot_h_FILE
    98  * @brief Topic sentence describing a function, if it goes over 79
    99  * characters, please put on the next line.
    100  */
    101 }}}
    102 
    103  *  Other header's @brief text for classes and files will show up in Function Descriptions. Use a topic sentence structure.
    104  *  End the other header's @brief with a period
    105 =====  Notes  =====
    106 
    107 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.
    108 =====  Checking Your Work '''(How to Run Doxygen)'''  =====
    109 
    110 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.
    111 
    112 '''Advice:''' please just use ONE method.
    113 =====  Method 1 '''Calling Doxygen Directly'''  =====
    114 
    115 
    116 1. Install doxygen
    117 1. Get the Doxyfile
    118  a. Copy the [wiki:File:Doxyfile.diff ] to a directory outside of the RTEMS directory.
    119  a. Rename Doxyfile.diff to Doxyfile.tar.gz
    120  a. Extract it outside the RTEMS directory
    121  a. 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
    122 1. call doxygen from the rtems directory
    123  ~/rtems> doxygen ../Doxyfile
    124  ~/rtems> firefox cpukit_doxy/html/index.html
    125 1. Click on Modules
    126 1. Click on your module
    127 1. ctrl+f Function Documentation
    128 
    129 Once you're done looking, delete the cpukit_doxy
    130 {{{
    131 ~/rtems> rm -rf cpukit_doxy
    132 }}}
    133 ===== Method 2 '''Using the do_doxygen script'''  =====
    134 
    135 '''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:
    136 {{{
    137 export r=~/rtems
    138 ./do_doxygen c/src/lib/libbsp
    139 }}}
    140 And it should just work.
    141 
    142 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 [wiki:Developer/VirtualMachines RTEMS Virtual Machine]. There is another shell script in that directory named ''build_doxygen'' which takes command line arguments.
    143 ===== Format the Patch '''(How to Run Doxygen)'''  =====
    144 
    145 Please submit a patch generated by git.
    146 
    147 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.
    148 
    149 You can do this with a git command similar to:
    150 {{{
    151 $ git diff > gci-doxygen-task2.diff
    152 }}}
    153 ==== Directions for RTEMS Mentors  ====
    154 
    155 '''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.
    156 
    157 '''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.
    158 
    159 '''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.
    1608
    1619== Cleanup Doxygen ==