Changes between Version 2 and Version 3 of Developer/Coding/Doxygen


Ignore:
Timestamp:
Oct 5, 2009, 4:09:06 PM (10 years ago)
Author:
Sh
Comment:

Rearranged sections.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Coding/Doxygen

    v2 v3  
    11= Doxygen Recommendations =
    22
    3 
    4 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].
    53=  Files  =
    64
    75You can document a file with the ''@file [filename]'' directive. If you omit the filename Doxygen will use it for the documentation of the file containing this directive.  This is the preferred way to document files which can be read by Doxygen. You should not use ''@file name_of_current_file'' to document the current file because this instructs Doxygen to document a file with the filename ''name_of_current_file'' and this is not necessarily the current one and may lead to ambiguity if someone from outside reuses your stuff to generate her documentation. Within one Doxygen run all files are unique and specified by the current Doxyfile. You can define how the generated output of path and filenames looks like in the Doxyfile via the
    86FULL_PATH_NAMES, STRIP_FROM_PATH and STRIP_FROM_INC_PATH options.
     7=  Functions  =
     8
     9For documentation of function arguments there are basically to ways: The first one uses @param:
     10{{{
     11/**
     12 * Copies bytes from a source memory area to a destination memory area,
     13 * where both areas may not overlap.
     14 * @param[out] dest The memory area to copy to.
     15 * @param[in]  src  The memory area to copy from.
     16 * @param[in]  n    The number of bytes to copy.
     17 */
     18}}}
     19
     20This leads likely to copy&paste within the comment, bloats simple function comments and is not very fluent to read.
     21
     22One alternative is this:
     23{{{
     24/**
     25 * Copies @a n bytes from a source memory area @a src to a destination memory
     26 * area @a dest, where both areas may not overlap.
     27 */
     28}}}
     29
     30The @a indicates that the next word is a function argument and deserves some kind of high-lightning.
     31=  Doxyfile Hints  =
     32
    933=  Header Files  =
    1034
     
    3761                  *.ac=script-comments-only
    3862}}}
    39 =  Assembly Example  =
     63==  Assembly Example  ==
    4064
    4165{{{
     
    5478}}}
    5579You have to put a declaration of this function somewhere in a header file.
    56 =  Script Example  =
     80==  Script Example  ==
    5781
    5882{{{
     
    6993AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
    7094}}}
    71 =  Functions  =
    72 
    73 For documentation of function arguments there are basically to ways: The first one uses @param:
    74 {{{
    75 /**
    76  * Copies bytes from a source memory area to a destination memory area,
    77  * where both areas may not overlap.
    78  * @param[out] dest The memory area to copy to.
    79  * @param[in]  src  The memory area to copy from.
    80  * @param[in]  n    The number of bytes to copy.
    81  */
    82 }}}
    83 
    84 This leads likely to copy&paste within the comment, bloats simple function comments and is not very fluent to read.
    85 
    86 One alternative is this:
    87 {{{
    88 /**
    89  * Copies @a n bytes from a source memory area @a src to a destination memory
    90  * area @a dest, where both areas may not overlap.
    91  */
    92 }}}
    93 
    94 The @a indicates that the next word is a function argument and deserves some kind of high-lightning.
    9595=  GCC Attributes  =
    9696
     
    103103
    104104}}}
    105 JAVADOC_AUTOBRIEF and QT_AUTOBRIEF  =
     105History  =
    106106
    107 We should agree on either NO or YES for both.
     107RTEMS 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].