[PATCH] eng/coding-doxygen: Convert wiki page to Rest
Marçal Comajoan Cara
mcomajoancara at gmail.com
Tue Dec 4 17:29:55 UTC 2018
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
More information about the devel
mailing list