[PATCH] eng/coding-doxygen: Convert wiki page to Rest
Joel Sherrill
joel at rtems.org
Tue Dec 4 19:34:24 UTC 2018
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 <
mcomajoancara at 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20181204/e265f408/attachment-0002.html>
More information about the devel
mailing list