Changes between Version 21 and Version 22 of Developer/Coding/Doxygen


Ignore:
Timestamp:
01/06/16 16:34:22 (7 years ago)
Author:
Ralph Holmes
Comment:

Removed advertising, again. Fixed link.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Coding/Doxygen

    v21 v22  
    22
    33=  Doxygen Best Practices  =
    4 
    54
    65 *  Do not use ''@a''.  Instead use ''@param'' to document function parameters.
     
    1211 *  Use dot comments for state diagrams.
    1312 *  Use one whitespace character after an asterisk.
     13
    1414=  Special Notes for Google Code In Students  =
    1515
    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
    1718=  Header File Example  =
    1819
     
    2223
    2324Header files should contain the similar comment blocks as other source files, described at [wiki:Developer/Coding/Boilerplate_File_Header Boilerplate File Header].
     25
    2426{{{
    2527/**
     
    4042
    4143}}}
     44
    4245=  Header guard  =
    4346
     
    4851
    4952}}}
     53
    5054=  Includes  =
    5155
    5256Then add your include files before protecting C declarations from C++.
     57
    5358{{{
    5459#include <rtems.h>
     
    5964
    6065}}}
     66
    6167=  Using @defgroup for group definitions  =
    6268
    6369Add 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
    6471{{{
    6572/**
     
    8895
    8996}}}
     97
    9098=  enum and struct  =
    9199
    92100Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix.
     101
    93102{{{
    94103/**
     
    119128} flip_flop_multiple;
    120129}}}
     130
    121131=  Using @name for organization  =
    122132
    123133Complicated 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
    124135{{{
    125136/**
     
    130141
    131142}}}
     143
    132144=  Declaring functions  =
    133145
    134146Function 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
    135148{{{
    136149/**
     
    155168
    156169Do not document trivial functions, such as getter/setter methods.
     170
    157171{{{
    158172flip_flop_state flip_flop_current_state(void);
     
    161175
    162176Close the documentation name definition and open a new name definition.
     177
    163178{{{
    164179/** @} */
     
    189204
    190205}}}
     206
    191207=  Ending the file  =
    192208
    193209Close the documentation group definition, then the extern C declarations, then the header guard.
     210
    194211{{{
    195212/** @} */
     
    201218#endif /* RTEMS_LIB_FLIP_FLOP_H */
    202219}}}
    203 No newline at the end of the file
     220
     221No newline at the end of the file.
     222
    204223=  Source File Example  =
    205224
     
    274293}
    275294}}}
     295
    276296=  Files  =
    277297
     
    280300
    281301For documentation of function arguments there are basically to ways: The first one uses @param:
     302
    282303{{{
    283304/**
     
    292313}}}
    293314
    294 The second is to use @a param in descriptive text, for example
     315The second is to use @a param in descriptive text, for example:
     316
    295317{{{
    296318/**
     
    323345                  rtems
    324346}}}
     347
    325348=  Script and Assembly Files  =
    326349
    327350Doxygen 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
    328352{{{
    329353FILTER_PATTERNS = *.S=c-comments-only \
     
    333357                  *.ac=script-comments-only
    334358}}}
     359
    335360==  Assembly Example  ==
    336361
     
    349374    LA r4, FMPLL_SYNCR
    350375}}}
     376
    351377You have to put a declaration of this function somewhere in a header file.
     378
    352379==  Script Example  ==
    353380
     
    365392AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
    366393}}}
     394
    367395=  GCC Attributes  =
    368396
    369397The Doxygen C/C++ parser cannot cope with the GCC __attribute__((something)) stuff. But you can discard such features with pre-defined preprocessor macros:
     398
    370399{{{
    371400ENABLE_PREPROCESSING = YES
     
    375404
    376405}}}
     406
    377407=  History  =
    378408
    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.
     409RTEMS 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].