Part of this is pushed. I made a sweep at coding-doxygen.rst before this arrived. Please see if I missed anything. If so, send a new patch.
THanks. On Tue, Dec 4, 2018 at 11:30 AM Marçal Comajoan Cara < mcomajoanc...@gmail.com> wrote: > Converted https://devel.rtems.org/wiki/Developer/Coding/Doxygen > to Rest, and TBDs and wiki TODOs into comments. Also added formattings, > updated > links to Header File Examples and updated the Script Example to include > https://devel.rtems.org/newticket instead of http://www.rtems.org/bugzilla > , > which is the old RTEMS Ticket System which may generate confusion. > > Added a label at the beginning of eng/coding-file-hdr.rst to be able to > link the page from eng/coding-doxygen.rst. > > This work was part of GCI 2018. > --- > eng/coding-doxygen.rst | 475 +++++++++++++++++++++++++++++++++++++++- > eng/coding-file-hdr.rst | 1 + > 2 files changed, 474 insertions(+), 2 deletions(-) > > diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst > index 5aafde0..6f98eed 100644 > --- a/eng/coding-doxygen.rst > +++ b/eng/coding-doxygen.rst > @@ -6,5 +6,476 @@ > General Doxygen Recommentations > =============================== > > -TBD - Convert the following to Rest and insert into this file > -TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen > +.. COMMENT: TBD - Convert the following to Rest and insert into this file > +.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen > + > +Doxygen Best Practices > +---------------------- > + > +* 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 write documentation for trivial functions. > +* Do not repeat documentation, use ``@see`` for example. > +* Do not use ``@note``. > +* Use groups and arrange them in a hierarchy. Put every file into at least > + one group. > +* Use dot comments for state diagrams. > +* Use one whitespace character after an asterisk. > + > +Special Notes for Google Code-in Students > +----------------------------------------- > + > +Follow the directions given by the `Google Code-in > +<https://devel.rtems.org/wiki/GCI>`_ task and this should take > +care of itself if in doubt ask a mentor and/or tell a mentor the decision > you > +made. > + > +Header File Example > +------------------- > + > +`thread.h > +<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h>`_ > and > +`threadimpl.h > +<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h > >`_ > +should be a good example of how a header file shouldbe written. The > following > +gives details in bits and pieces. > + > +Header blocks > +------------- > + > +Header files should contain the similar comment blocks as other source > files, > +described at :ref:`coding-file-hdr`. > + > +.. code-block:: c > + > + /** > + * @file > + * > + * @ingroup FlipFlop > + * > + * @brief Flip-Flop API > + */ > + > + /* > + * Copyright (c) YYYY Author. > + * > + * The license and distribution terms for this file may be > + * found in the file LICENSE in this distribution or at > + * http://www.rtems.com/license/LICENSE. > + */ > + > +Header guard > +------------ > + > +After the comment blocks, use a header guard that assembles at least the > +include path of the file. For example, if ``flipflop.h`` is in > +``<rtems/lib/flipflop.h>`` then > + > +.. code-block:: c > + > + #ifndef RTEMS_LIB_FLIP_FLOP_H > + #define RTEMS_LIB_FLIP_FLOP_H > + > +Includes > +-------- > + > +Then add your include files before protecting C declarations from C++. > + > +.. code-block:: c > + > + #include <rtems.h> > + > + #ifdef __cplusplus > + extern "C" { > + #endif /* __cplusplus */ > + > +Using @defgroup for group definitions > +------------------------------------- > + > +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. > + > +.. code-block:: c > + > + /** > + * @defgroup FlipFlop Flip-Flop > + * > + * @brief Simple Flip-Flop state machine. > + * > + * @dot > + * digraph { > + * start [label="START"]; > + * flip [label="FLIP"]; > + * flop [label="FLOP"]; > + * flip -> flop [label="flop()", URL="\ref flop"]; > + * flop -> flip [label="flip()", URL="\ref flip"]; > + * start -> flip > + * [label="flip_flop_initialize(FLIP)", URL="\ref > flip_flop_initialize"]; > + * start -> flop > + * [label="flip_flop_initialize(FLOP)", URL="\ref > flip_flop_initialize"]; > + * flip -> start > + * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; > + * } > + * @enddot > + * > + * @{ > + */ > + > +enum and struct > +--------------- > + > +Provide documentation for declarations of enumerated types and structs. > +Use typedefs for structs, and do not use ``_t`` as a typename suffix. > + > +.. code-block:: c > + > + /** > + * @brief The set of possible flip-flop states. > + * > + * Enumerated type to define the set of states for a flip-flop. > + */ > + typedef enum { > + START = 0, > + FLIP, > + 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; > + > +Using @name for organization > +---------------------------- > + > +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. > + > +.. code-block:: c > + > + /** > + * @name Flip-Flop Maintenance > + * > + * @{ > + */ > + > +Declaring functions > +------------------- > + > +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. > + > +.. 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 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. > + > +.. code-block:: c > + > + flip_flop_state flip_flop_current_state(void); > + > +Close the documentation name definition and open a new name definition. > + > +.. code-block:: c > + > + /** @} */ > + > + /** > + * @name Flip-Flop Usage > + * > + * @{ > + */ > + > + /** > + * @brief Flip operation. > + * > + * @retval RTEMS_SUCCESSFUL Flipped successfully. > + * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. > + */ > + rtems_status_code flip( void ); > + > + /** > + * @brief Flop operation. > + * > + * @retval RTEMS_SUCCESSFUL Flopped successfully. > + * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. > + */ > + rtems_status_code flop( void ); > + > + /** @} */ > + > +Ending the file > +--------------- > + > +Close the documentation group definition, then the extern C declarations, > +then the header guard. > + > +.. code-block:: c > + > + /** @} */ > + > + #ifdef __cplusplus > + } > + #endif /* __cplusplus */ > + > + #endif /* RTEMS_LIB_FLIP_FLOP_H */ > + > + No newline at the end of the file. > + > +Source File Example > +------------------- > + > +.. code-block:: c > + > + /** > + * @file > + * > + * @ingroup FlipFlop > + * > + * @brief Flip-Flop implementation. > + */ > + > + /* > + * Copyright (c) YYYY Author. > + * > + * The license and distribution terms for this file may be > + * found in the file LICENSE in this distribution or at > + * http://www.rtems.com/license/LICENSE. > + */ > + > + #include <rtems/lib/flipflop.h> > + > + static flip_flop_state current_state; > + > + rtems_status_code flip_flop_initialize(flip_flop_state state) > + { > + if (current_state == START) { > + current_state = state; > + > + return RTEMS_SUCCESSFUL; > + } else { > + return RTEMS_INCORRECT_STATE; > + } > + } > + > + rtems_status_code flip_flop_restart(void) > + { > + if (current_state == FLIP) { > + current_state = START; > + > + return RTEMS_SUCCESSFUL; > + } else { > + return RTEMS_INCORRECT_STATE; > + } > + } > + > + flip_flop_state flip_flop_current_state(void) > + { > + return current_state; > + } > + > + rtems_status_code flip(void) > + { > + if (current_state == FLOP) { > + current_state = FLIP; > + > + return RTEMS_SUCCESSFUL; > + } else { > + return RTEMS_INCORRECT_STATE; > + } > + } > + > + rtems_status_code flop(void) > + { > + if (current_state == FLIP) { > + current_state = FLOP; > + > + return RTEMS_SUCCESSFUL; > + } else { > + return RTEMS_INCORRECT_STATE; > + } > + } > + > +Files > +----- > +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. > + > +Functions > +--------- > + > +For documentation of function arguments there are basically to ways: > + > +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: > + > +.. 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``. > + > +.. COMMENT: TBD - Add Doxyfile Hints > + > +Header Files > +------------ > + > +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: > + > +.. code-block:: > + > + INPUT = rtems/bsps/powerpc/mybsp \ > + rtems/c/src/lib/libcpu/powerpc/mycpu \ > + rtems/make/custom/mybsp.cfg \ > + build/powerpc-rtems5/mybsp/lib/include/myincludes > + > + RECURSIVE = YES > + > + EXCLUDE = rtems/bsps/powerpc/mybsp/include \ > + rtems/c/src/lib/libcpu/powerpc/mycpu/include > + > + FULL_PATH_NAMES = YES > + > + STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ > + rtems > + > +Script and Assembly Files > +------------------------- > + > +Doxygen cannot cope with script (= files with #-like comments) or > assembly files. > +But you can add filter programs for them > + > +.. COMMENT: TBD - Add source code for filter programs somewhere > + > +.. code-block:: > + > + FILTER_PATTERNS = *.S=c-comments-only \ > + *.s=c-comments-only \ > + *.cfg=script-comments-only \ > + *.am=script-comments-only \ > + *.ac=script-comments-only > + > +Assembly Example > +~~~~~~~~~~~~~~~~ > + > +.. code-block:: c > + > + /** > + * @fn void mpc55xx_fmpll_reset_config() > + * > + * @brief Configure FMPLL after reset. > + * > + * Sets the system clock from 12 MHz in two steps up to 128 MHz. > + */ > + GLOBAL_FUNCTION mpc55xx_fmpll_reset_config > + /* Save link register */ > + mflr r3 > + > + LA r4, FMPLL_SYNCR > + > +You have to put a declaration of this function somewhere in a header file. > + > +Script Example > +~~~~~~~~~~~~~~ > + > +.. code-block:: python > + > + ## > + # > + # @file > + # > + # @ingroup mpc55xx_config > + # > + # @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]) > + > + > +GCC Attributes > +-------------- > + > +The Doxygen C/C++ parser cannot cope with the GCC > ``attribute((something))`` stuff. > +But you can discard such features with pre-defined preprocessor macros > + > +.. code-block:: none > + > + ENABLE_PREPROCESSING = YES > + MACRO_EXPANSION = YES > + EXPAND_ONLY_PREDEF = YES > + PREDEFINED = __attribute__(x)= > + > +History > +------- > + > +RTEMS is much older than `Doxygen <http://www.doxygen.org/>`_ and the > +documentation in the .h and .inl files was obviously not written with > +`Doxygen markup <http://www.stack.nl/~dimitri/doxygen/manual.html>`_. In > +2007, Joel Sherrill undertook to convert 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 development version of the RTEMS SuperCore is now > built automatically > +multiple times per day and made available on the RTEMS Website. In April > 2008, > +Joel Sherrill began to update the Classic API (e.g. cpukit/rtems) .h and > .inl > +files to include Doxygen markup. > + > diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst > index 1ff16b8..f273e03 100644 > --- a/eng/coding-file-hdr.rst > +++ b/eng/coding-file-hdr.rst > @@ -7,6 +7,7 @@ > .. COMMENT:TBD - Convert the following to Rest and insert into this file > .. COMMENT:TBD - > https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header > > +.. _coding-file-hdr: > > Boilerplate File Header > ======================= > -- > 2.17.1 > >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
