![[RTEMS Logo]](/images/logo.png){kind=logo}
Changes between Version 21 and Version 22 of Developer/Coding/Doxygen
- Timestamp:
- 01/06/16 16:34:22 (8 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Developer/Coding/Doxygen
v21 v22 2 2 3 3 = Doxygen Best Practices = 4 5 4 6 5 * Do not use ''@a''. Instead use ''@param'' to document function parameters. … … 12 11 * Use dot comments for state diagrams. 13 12 * Use one whitespace character after an asterisk. 13 14 14 = Special Notes for Google Code In Students = 15 15 16 * Follow the directions on the [wiki:GCI/Projects Google Code In Projects] and this should take care of itself, if in doubt ask a mentor and/or tell a mentor the decision you made 16 * Follow the directions on the [wiki:GCI/Projects Google Code In Projects] and this should take care of itself, if in doubt ask a mentor and/or tell a mentor the decision you made. 17 17 18 = Header File Example = 18 19 … … 22 23 23 24 Header files should contain the similar comment blocks as other source files, described at [wiki:Developer/Coding/Boilerplate_File_Header Boilerplate File Header]. 25 24 26 {{{ 25 27 /** … … 40 42 41 43 }}} 44 42 45 = Header guard = 43 46 … … 48 51 49 52 }}} 53 50 54 = Includes = 51 55 52 56 Then add your include files before protecting C declarations from C++. 57 53 58 {{{ 54 59 #include <rtems.h> … … 59 64 60 65 }}} 66 61 67 = Using @defgroup for group definitions = 62 68 63 69 Add any group definitions surrounding the function declarations that belong in that group. Rarely, a header may define more than one group. Here we use a dot diagram. 70 64 71 {{{ 65 72 /** … … 88 95 89 96 }}} 97 90 98 = enum and struct = 91 99 92 100 Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix. 101 93 102 {{{ 94 103 /** … … 119 128 } flip_flop_multiple; 120 129 }}} 130 121 131 = Using @name for organization = 122 132 123 133 Complicated groups can be given additional organization by using @name, or by declaring additional groups within the hierarchy of the header file's top-level group. 134 124 135 {{{ 125 136 /** … … 130 141 131 142 }}} 143 132 144 = Declaring functions = 133 145 134 146 Function declarations should have an @brief that states what the function does in a single topic sentence starting with a descriptive verb in the present tense. 147 135 148 {{{ 136 149 /** … … 155 168 156 169 Do not document trivial functions, such as getter/setter methods. 170 157 171 {{{ 158 172 flip_flop_state flip_flop_current_state(void); … … 161 175 162 176 Close the documentation name definition and open a new name definition. 177 163 178 {{{ 164 179 /** @} */ … … 189 204 190 205 }}} 206 191 207 = Ending the file = 192 208 193 209 Close the documentation group definition, then the extern C declarations, then the header guard. 210 194 211 {{{ 195 212 /** @} */ … … 201 218 #endif /* RTEMS_LIB_FLIP_FLOP_H */ 202 219 }}} 203 No newline at the end of the file 220 221 No newline at the end of the file. 222 204 223 = Source File Example = 205 224 … … 274 293 } 275 294 }}} 295 276 296 = Files = 277 297 … … 280 300 281 301 For documentation of function arguments there are basically to ways: The first one uses @param: 302 282 303 {{{ 283 304 /** … … 292 313 }}} 293 314 294 The second is to use @a param in descriptive text, for example 315 The second is to use @a param in descriptive text, for example: 316 295 317 {{{ 296 318 /** … … 323 345 rtems 324 346 }}} 347 325 348 = Script and Assembly Files = 326 349 327 350 Doxygen cannot cope with script (= files with #-like comments) or assembly files. But you can add filter programs for them (TODO: Add source code for filter programs somewhere): 351 328 352 {{{ 329 353 FILTER_PATTERNS = *.S=c-comments-only \ … … 333 357 *.ac=script-comments-only 334 358 }}} 359 335 360 == Assembly Example == 336 361 … … 349 374 LA r4, FMPLL_SYNCR 350 375 }}} 376 351 377 You have to put a declaration of this function somewhere in a header file. 378 352 379 == Script Example == 353 380 … … 365 392 AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) 366 393 }}} 394 367 395 = GCC Attributes = 368 396 369 397 The Doxygen C/C++ parser cannot cope with the GCC __attribute__((something)) stuff. But you can discard such features with pre-defined preprocessor macros: 398 370 399 {{{ 371 400 ENABLE_PREPROCESSING = YES … … 375 404 376 405 }}} 406 377 407 = History = 378 408 379 RTEMS is much older than [http://www.doxygen.org Doxygen] and the documentation in the .h and .inl files was obviously not written with [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen markup]. In 2007, [wiki:TBR/User/JoelSherrill JoelSherrill] undertook converting the documentation in the .h and .inl files in the RTEMS SuperCore to Doxygen format. As a result of this effort, the Doxygen for the CVS version of the RTEMS SuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, [wiki:TBR/User/JoelSherrill JoelSherrill] began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include [http://www. research-service.com/custom-research-paper.html custom research paper] on Doxygen.409 RTEMS is much older than [http://www.doxygen.org Doxygen] and the documentation in the .h and .inl files was obviously not written with [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen markup]. In 2007, [wiki:TBR/User/JoelSherrill JoelSherrill] undertook converting the documentation in the .h and .inl files in the RTEMS SuperCore to Doxygen format. As a result of this effort, the Doxygen for the CVS version of the RTEMS SuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, [wiki:TBR/User/JoelSherrill JoelSherrill] began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen markup].
