rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 11:08:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng/coding-doxygen: Fix errors

Browse Source 
This work was part of GCI 2018.
This commit is contained in:
Marçal Comajoan Cara 2018-12-05 15:43:00 +01:00 committed by Joel Sherrill
parent b8b4f14973
commit cc826d74f3
1 changed files with 330 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

652
eng/coding-doxygen.rst
View File

@ -4,10 +4,10 @@
.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
General Doxygen Recommentations General Doxygen Recommentations
------------------------------- ===============================
TBD - Convert the following to Rest and insert into this file .. COMMENT: TBD - Convert the following to Rest and insert into this file
TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen .. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
.. sidebar:: *History* .. sidebar:: *History*
@ -23,451 +23,459 @@ TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
diagrams. diagrams.
Doxygen Best Practices Doxygen Best Practices
^^^^^^^^^^^^^^^^^^^^^^ ----------------------
* Do not use @a. Instead use @param to document function parameters. * Do not use ``@a``. Instead use ``@param`` to document function parameters.
* Do not use @return. Instead use @retval to document return status codes. * Do not use ``@return``. Instead use ``@retval`` to document return status
codes.
* Do not write documentation for trivial functions. * Do not write documentation for trivial functions.
* Do not repeat documentation, use @see for example. * Do not repeat documentation, use ``@see`` for example.
* Do not use @note. * Do not use ``@note``.
* Use groups and arrange them in a hierarchy. Put every file into at least one group. * Use groups and arrange them in a hierarchy. Put every file into at least
one group.
* Use dot comments for state diagrams. * Use dot comments for state diagrams.
* Use one whitespace character after an asterisk. * Use one whitespace character after an asterisk.
Special Notes for Google Code In Students Special Notes for Google Code-in Students
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------------------
* Follow the directions given by the `Google Code In Follow the directions given by the `Google Code-in
<https://devel.rtems.org/wiki/GCI>`_ task and this should take care <https://devel.rtems.org/wiki/GCI>`_ task and this should take
of itself if in doubt ask a mentor and/or tell a mentor the decision care of itself if in doubt ask a mentor and/or tell a mentor the decision you
you made. made.
Header File Example Header File Example
^^^^^^^^^^^^^^^^^^^ -------------------
The files *thread.h* `thread.h
(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h) <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h>`_ and
and *threadimpl.h* `threadimpl.h
(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h) <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h>`_
should be a good example of how a header file should be written. The should be a good example of how a header file shouldbe written. The following
following gives details in bits and pieces. gives details in bits and pieces.
Header blocks Header blocks
^^^^^^^^^^^^^ -------------
Header files should contain the similar comment blocks as other source files, described at `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_. Header files should contain the similar comment blocks as other source files,
described at :ref:`coding-file-hdr`.
.. code-block:: c .. code-block:: c
/** /**
* @file * @file
* *
* @ingroup FlipFlop * @ingroup FlipFlop
* *
* @brief Flip-Flop API * @brief Flip-Flop API
*/ */
/* /*
* Copyright (c) YYYY Author. * Copyright (c) YYYY Author.
* *
* The license and distribution terms for this file may be * The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at * found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE. * http://www.rtems.com/license/LICENSE.
*/ */
Header Guard Header guard
^^^^^^^^^^^^ ------------
After the comment blocks, use a header guard that assembles at After the comment blocks, use a header guard that assembles at least the
least the include path of the file. For example, if flipflop.h is in include path of the file. For example, if ``flipflop.h`` is in
<rtems/lib/flipflop.h> then ``<rtems/lib/flipflop.h>`` then
.. code-block:: c .. code-block:: c
#ifndef RTEMS_LIB_FLIP_FLOP_H #ifndef RTEMS_LIB_FLIP_FLOP_H
#define RTEMS_LIB_FLIP_FLOP_H #define RTEMS_LIB_FLIP_FLOP_H
Includes Includes
^^^^^^^^ --------
Then add your include files before protecting C declarations from C++. Then add your include files before protecting C declarations from C++.
.. code-block:: c
.. code-block:: c #include <rtems.h>
#include <rtems.h> #ifdef __cplusplus
extern "C" {
#ifdef __cplusplus #endif /* __cplusplus */
extern "C" {
#endif /* __cplusplus */
Using @defgroup for group definitions Using @defgroup for group definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -------------------------------------
Add any group definitions surrounding the function declarations Add any group definitions surrounding the function declarations that belong
that belong in that group. Rarely, a header may define more than one in that group. Rarely, a header may define more than one group. Here we use
group. Here we use a dot diagram. a dot diagram.
.. code-block:: c
.. code-block:: c /**
* @defgroup FlipFlop Flip-Flop
/** *
* @defgroup FlipFlop Flip-Flop * @brief Simple Flip-Flop state machine.
* *
* @brief Simple Flip-Flop state machine. * @dot
* * digraph {
* @dot * start [label="START"];
* digraph { * flip [label="FLIP"];
* start [label="START"]; * flop [label="FLOP"];
* flip [label="FLIP"]; * flip -> flop [label="flop()", URL="\ref flop"];
* flop [label="FLOP"]; * flop -> flip [label="flip()", URL="\ref flip"];
* flip -> flop [label="flop()", URL="\ref flop"]; * start -> flip
* flop -> flip [label="flip()", URL="\ref flip"]; * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
* start -> flip * start -> flop
* [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
* start -> flop * flip -> start
* [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; * [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
* flip -> start * }
* [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; * @enddot
* } *
* @enddot * @{
* */
* @{
*/
enum and struct enum and struct
^^^^^^^^^^^^^^^ ---------------
Provide documentation for declarations of enumerated types and Provide documentation for declarations of enumerated types and structs.
structs. Use typedefs for structs, and do not use _t as a typename suffix. Use typedefs for structs, and do not use ``_t`` as a typename suffix.
.. code-block:: c
.. code-block:: c /**
* @brief The set of possible flip-flop states.
/** *
* @brief The set of possible flip-flop states. * Enumerated type to define the set of states for a flip-flop.
* */
* Enumerated type to define the set of states for a flip-flop. typedef enum {
*/ START = 0,
typedef enum { FLIP,
START = 0, FLOP
FLIP, } flip_flop_state;
FLOP
} flip_flop_state;
/**
* @brief Object containing multiple flip-flops.
*
* Encapsulates multiple flip-flops.
*/
typedef struct {
/**
* @brief Primary flip-flop.
*/
flip_flop_state primary;
/**
* @brief Secondary flip-flop.
*/
flip_flop_state secondary;
} flip_flop_multiple;
/**
* @brief Object containing multiple flip-flops.
*
* Encapsulates multiple flip-flops.
*/
typedef struct {
/**
* @brief Primary flip-flop.
*/
flip_flop_state primary;
/**
* @brief Secondary flip-flop.
*/
flip_flop_state secondary;
} flip_flop_multiple;
Using @name for organization Using @name for organization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------
Complicated groups can be given additional organization by using @name, Complicated groups can be given additional organization by using ``@name``, or
or by declaring additional groups within the hierarchy of the header by declaring additional groups within the hierarchy of the header file's
file's top-level group. top-level group.
.. code-block:: c .. code-block:: c
/** /**
* @name Flip-Flop Maintenance * @name Flip-Flop Maintenance
* *
* @{ * @{
*/ */
Declaring functions Declaring functions
^^^^^^^^^^^^^^^^^^^ -------------------
Function declarations should have an @brief that states what the function Function declarations should have an @brief that states what the function does
does in a single topic sentence starting with a descriptive verb in the in a single topic sentence starting with a descriptive verb in the present
present tense. tense.
.. code-block:: c
.. code-block:: c /**
* @brief Initializes the flip-flop state.
*
* @param[in] state The initial state to set the flip-flop.
*
* @retval RTEMS_SUCCESSFUL Successfully initialized.
* @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
*/
rtems_status_code flip_flop_initialize(flip_flop_state state);
/** /**
* @brief Initializes the flip-flop state. * @brief Restarts the flip-flop.
* *
* @param[in] state The initial state to set the flip-flop. * @retval RTEMS_SUCCESSFUL Successfully restarted.
* * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
* @retval RTEMS_SUCCESSFUL Successfully initialized. */
* @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. rtems_status_code flip_flop_restart(void);
*/
rtems_status_code flip_flop_initialize(flip_flop_state state);
/**
* @brief Restarts the flip-flop.
*
* @retval RTEMS_SUCCESSFUL Successfully restarted.
* @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
*/
rtems_status_code flip_flop_restart(void);
Do not document trivial functions, such as getter/setter methods. Do not document trivial functions, such as getter/setter methods.
.. code-block:: c .. code-block:: c
flip_flop_state flip_flop_current_state(void); flip_flop_state flip_flop_current_state(void);
Close the documentation name definition and open a new name definition. Close the documentation name definition and open a new name definition.
.. code-block:: c .. code-block:: c
/** @} */ /** @} */
/** /**
* @name Flip-Flop Usage * @name Flip-Flop Usage
* *
* @{ * @{
*/ */
/** /**
* @brief Flip operation. * @brief Flip operation.
* *
* @retval RTEMS_SUCCESSFUL Flipped successfully. * @retval RTEMS_SUCCESSFUL Flipped successfully.
* @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
*/ */
rtems_status_code flip( void ); rtems_status_code flip( void );
/** /**
* @brief Flop operation. * @brief Flop operation.
* *
* @retval RTEMS_SUCCESSFUL Flopped successfully. * @retval RTEMS_SUCCESSFUL Flopped successfully.
* @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
*/ */
rtems_status_code flop( void ); rtems_status_code flop( void );
/** @} */ /** @} */
Ending the file Ending the file
^^^^^^^^^^^^^^^ ---------------
Close the documentation group definition, then the extern C declarations, Close the documentation group definition, then the extern C declarations,
then the header guard. then the header guard.
.. code-block:: c .. code-block:: c
/** @} */ /** @} */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif /* __cplusplus */ #endif /* __cplusplus */
#endif /* RTEMS_LIB_FLIP_FLOP_H */ #endif /* RTEMS_LIB_FLIP_FLOP_H */
No newline at the end of the file. No newline at the end of the file.
Source File Example Source File Example
^^^^^^^^^^^^^^^^^^^ -------------------
.. code-block:: c .. code-block:: c
/** /**
* @file * @file
* *
* @ingroup FlipFlop * @ingroup FlipFlop
* *
* @brief Flip-Flop implementation. * @brief Flip-Flop implementation.
*/ */
/* /*
* Copyright (c) YYYY Author. * Copyright (c) YYYY Author.
* *
* The license and distribution terms for this file may be * The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at * found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE. * http://www.rtems.com/license/LICENSE.
*/ */
#include <rtems/lib/flipflop.h> #include <rtems/lib/flipflop.h>
static flip_flop_state current_state; static flip_flop_state current_state;
rtems_status_code flip_flop_initialize(flip_flop_state state) rtems_status_code flip_flop_initialize(flip_flop_state state)
{ {
if (current_state == START) { if (current_state == START) {
current_state = state; current_state = state;
return RTEMS_SUCCESSFUL; return RTEMS_SUCCESSFUL;
} else { } else {
return RTEMS_INCORRECT_STATE; return RTEMS_INCORRECT_STATE;
} }
} }
rtems_status_code flip_flop_restart(void) rtems_status_code flip_flop_restart(void)
{ {
if (current_state == FLIP) { if (current_state == FLIP) {
current_state = START; current_state = START;
return RTEMS_SUCCESSFUL; return RTEMS_SUCCESSFUL;
} else { } else {
return RTEMS_INCORRECT_STATE; return RTEMS_INCORRECT_STATE;
} }
} }
flip_flop_state flip_flop_current_state(void) flip_flop_state flip_flop_current_state(void)
{ {
return current_state; return current_state;
} }
rtems_status_code flip(void) rtems_status_code flip(void)
{ {
if (current_state == FLOP) { if (current_state == FLOP) {
current_state = FLIP; current_state = FLIP;
return RTEMS_SUCCESSFUL; return RTEMS_SUCCESSFUL;
} else { } else {
return RTEMS_INCORRECT_STATE; return RTEMS_INCORRECT_STATE;
} }
} }
rtems_status_code flop(void) rtems_status_code flop(void)
{ {
if (current_state == FLIP) { if (current_state == FLIP) {
current_state = FLOP; current_state = FLOP;
return RTEMS_SUCCESSFUL; return RTEMS_SUCCESSFUL;
} else { } else {
return RTEMS_INCORRECT_STATE; return RTEMS_INCORRECT_STATE;
} }
} }
Files Files
^^^^^ -----
Document files with the ``@file`` directive omitting the optional filename
Document files with the @file directive omitting the optional filename argument. Doxygen will infer the filename from the actual name of the file. Within one Doxygen run all files are unique and specified by the current Doxyfile. We can define how the generated output of path and filenames looks like in the Doxyfile via the FULL_PATH_NAMES, STRIP_FROM_PATH and STRIP_FROM_INC_PATH options. argument. Doxygen will infer the filename from the actual name of the file.
Within one Doxygen run all files are unique and specified by the current
Doxyfile. We can define how the generated output of path and filenames looks
like in the Doxyfile via the ``FULL_PATH_NAMES``, ``STRIP_FROM_PATH`` and
``STRIP_FROM_INC_PATH`` options.
Functions Functions
^^^^^^^^^ ---------
For documentation of function arguments there are basically to ways: The first one uses @param: For documentation of function arguments there are basically to ways:
.. code-block:: The first one uses ``@param``:
/** .. code-block:: c
* @brief Copies from a source to a destination memory area.
*
* The source and destination areas may not overlap.
*
* @param[out] dest The destination memory area to copy to.
* @param[in] src The source memory area to copy from.
* @param[in] n The number of bytes to copy.
*/
The second is to use @a param in descriptive text, for example:
/** /**
* Copies @a n bytes from a source memory area @a src to a destination memory * @brief Copies from a source to a destination memory area.
* area @a dest, where both areas may not overlap. *
*/ * The source and destination areas may not overlap.
*
* @param[out] dest The destination memory area to copy to.
* @param[in] src The source memory area to copy from.
* @param[in] n The number of bytes to copy.
*/
The @a indicates that the next word is a function argument and deserves some kind of highlighting. However, we feel that @a buries the usage of function arguments within description text. In RTEMS sources, we prefer to use @param instead of @a. The second is to use ``@a`` param in descriptive text, for example:
.. code-block:: c
/**
* Copies @a n bytes from a source memory area @a src to a destination memory
* area @a dest, where both areas may not overlap.
*/
The ``@a`` indicates that the next word is a function argument and deserves
some kind of highlighting. However, we feel that ``@a`` buries the usage of
function arguments within description text. In RTEMS sources, we prefer to
use ``@param`` instead of ``@a``.
Doxyfile Hints Doxyfile Hints
^^^^^^^^^^^^^^ --------------
Header Files Header Files
------------ ~~~~~~~~~~~
TBD - This is out of date since the include file reorganizaiton It is an RTEMS build feature that header files need to be installed in order to
be useful. One workaround to generate documentation which allows automatic
link generation is to use the installed header files as documentation input.
Assume that we have the RTEMS sources in the rtems directory and the build of
our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory.
Then you can configure Doxygen like:
It is an RTEMS build feature that header files need to be installed .. code-block::
in order to be useful. One workaround to generate documentation which
allows automatic link generation is to use the installed header files as
documentation input. Assume that we have the RTEMS sources in the rtems
directory and the build of our BSP in build/powerpc-rtems5/mybsp relative
to a common top-level directory. Then you can configure Doxygen like:
INPUT = rtems/bsps/powerpc/mybsp \
rtems/c/src/lib/libcpu/powerpc/mycpu \
rtems/make/custom/mybsp.cfg \
build/powerpc-rtems5/mybsp/lib/include/myincludes
.. code-block:: RECURSIVE = YES
INPUT = rtems/bsps/powerpc/mybsp \ EXCLUDE = rtems/bsps/powerpc/mybsp/include \
rtems/c/src/lib/libcpu/powerpc/mycpu \ rtems/c/src/lib/libcpu/powerpc/mycpu/include
rtems/make/custom/mybsp.cfg \
build/powerpc-rtems5/mybsp/lib/include/myincludes
RECURSIVE = YES FULL_PATH_NAMES = YES
EXCLUDE = rtems/bsps/powerpc/mybsp/include \ STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
rtems/c/src/lib/libcpu/powerpc/mycpu/include rtems
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
rtems
Script and Assembly Files Script and Assembly Files
^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~
Doxygen cannot cope with script (= files with #-like comments) or assembly Doxygen cannot cope with script (= files with #-like comments) or assembly
files. But you can add filter programs for them (TODO: Add source code files. But you can add filter programs for them
for filter programs somewhere):
.. code-block:: .. COMMENT: TBD - Add source code for filter programs somewhere
FILTER_PATTERNS = *.S=c-comments-only \ .. code-block::
*.s=c-comments-only \
*.cfg=script-comments-only \ FILTER_PATTERNS = *.S=c-comments-only \
*.am=script-comments-only \ *.s=c-comments-only \
*.ac=script-comments-only *.cfg=script-comments-only \
*.am=script-comments-only \
*.ac=script-comments-only
Assembly Example Assembly Example
^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~
.. code-block:: .. code-block:: c
/** /**
* @fn void mpc55xx_fmpll_reset_config() * @fn void mpc55xx_fmpll_reset_config()
* *
* @brief Configure FMPLL after reset. * @brief Configure FMPLL after reset.
* *
* Sets the system clock from 12 MHz in two steps up to 128 MHz. * Sets the system clock from 12 MHz in two steps up to 128 MHz.
*/ */
GLOBAL_FUNCTION mpc55xx_fmpll_reset_config GLOBAL_FUNCTION mpc55xx_fmpll_reset_config
/* Save link register */ /* Save link register */
mflr r3 mflr r3
LA r4, FMPLL_SYNCR LA r4, FMPLL_SYNCR
You have to put a declaration of this function somewhere in a header file. You have to put a declaration of this function somewhere in a header file.
Script Example Script Example
^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~
.. code-block:: shell .. code-block:: shell
## ##
# #
# @file # @file
# #
# @ingroup mpc55xx_config # @ingroup mpc55xx_config
# #
# @brief Configure script of LibBSP for the MPC55xx evaluation boards. # @brief Configure script of LibBSP for the MPC55xx evaluation boards.
# #
AC_PREREQ([2.69])
AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[https://devel.rtems.org/newticket])
AC_PREREQ(2.60)
AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
GCC Attributes GCC Attributes
^^^^^^^^^^^^^^ --------------
The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) The Doxygen C/C++ parser cannot cope with the GCC ``attribute((something))``
stuff. But you can discard such features with pre-defined preprocessor stuff. But you can discard such features with pre-defined preprocessor macros
macros:
.. code-block:: shell .. code-block:: shell
ENABLE_PREPROCESSING = YES ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)= PREDEFINED = __attribute__(x)=