[PATCH] eng: Rework and clarify Doxygen Guidelines

Joel Sherrill joel at rtems.org
Mon Nov 9 14:12:16 UTC 2020


On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> ---
>  eng/coding-doxygen.rst  | 210 ++++++++++++++++++++++++++++------------
>  eng/coding-file-hdr.rst |   2 +
>  2 files changed, 149 insertions(+), 63 deletions(-)
>
> diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst
> index f4308ef..b2e6b61 100644
> --- a/eng/coding-doxygen.rst
> +++ b/eng/coding-doxygen.rst
> @@ -16,12 +16,13 @@ In the RTEMS source code, CamelCase is rarely used, so
> this makes it easier to
>  search and replace Doxygen groups.  It avoids ambiguous references to
>  functions, types, defines, macros, and groups.  All groups shall have an
>  ``RTEMS`` prefix.  This makes it possible to include the RTEMS files with
> -Doxygen comments in a larger project without name conflicts.
> +Doxygen comments in a larger project without name conflicts.  The group
> name
> +shall use `Title Case <
> https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_.
>
>  .. code:: c
>
>      /**
> -     * @defgroup RTEMSScoreThread
> +     * @defgroup RTEMSScoreThread Thread Handler
>       *
>       * @ingrop RTEMSScore
>       *
> @@ -36,18 +37,28 @@ global variable declaration shall belong to at least
> one Doxygen group.  Use
>  ``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets to add
>  members to a group.  A group shall be defined at most once.  Each group
> shall
>  be documented with an ``@brief`` description and an optional detailed
> -description.  The ``@brief`` description shall use
> -`Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_.
> -Use grammatically correct sentences for the detailed descriptions.
> +description.  Use grammatically correct sentences for the ``@brief`` and
> +detailed descriptions.
> +
> +For the ``@brief`` description use phrases like this:
> +
> +* This group contains ... and so on.
> +
> +* The XYZ Handler provides ... and so on.
> +
> +* The ABC Component contains ... and so on.
>

I don't know where the idea @brief should be short sentences came from.
@brief is used to make table of contents type pages and those should
read more like titles than the first sentence of the detailed description.

https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html

If you look at the PDF, it really is used for the Table of Contents and
a sentence is quite odd there.

It should read like a chapter title

>
>  .. code:: c
>
>      /**
> -     * @defgroup RTEMSScoreThread
> +     * @defgroup RTEMSScoreThread Thread Handler
>       *
>       * @ingrop RTEMSScore
>       *
> -     * @brief Thread Handler
> +     * @brief The Thread Handler provides functionality related to the
> +     *   management of threads.
> +     *
> +     * This includes the creation, deletion, and scheduling of threads.
>

No. The sentence you wrote would be better as the first sentence of the
description paragraph.

>       *
>       * ...
>       *
> @@ -73,24 +84,33 @@ Use grammatically correct sentences for the detailed
> descriptions.
>  Files
>  -----
>
> -Each source or header file shall have an ``@file`` block at the top of the
> -file.  The ``@file`` block should precede the license header separated by
> one
> -blank line.  This placement reduces the chance of merge conflicts in
> imported
> -third-party code.  The ``@file`` block shall be put into a group with
> -``@ingroup GroupName``.  The ``@file`` block should have an ``@brief``
> -description and a detailed description if it is considered helpful.  Use
> -``@brief @copybrief GroupName`` as a default to copy the ``@brief``
> description
> -from the corresponding group and omit the detailed description.
> +Each header and source file shall have an ``@file`` block at the top of
> the
> +file after the SPDX License Identifier.  The ``@file`` block shall
> precede the
> +license header separated by one blank line, see
> :ref:`CCXXHeaderFileTemplate`
> +and :ref:`CCXXASMSourceFileTemplate`.  The ``@file`` block shall be put
> into a
> +group with ``@ingroup GroupName``.  The ``@file`` block shall have an
> +``@brief`` description and an optional detailed description.  The detailed
> +description could give an explanation why a certain set of functions or
> data
> +structures is grouped in one file.  Use grammatically correct sentences
> for the
> +``@brief`` and detailed descriptions.
>
> -.. code:: c
> +For the ``@brief`` description of header files use phrases like this:
>
> -    /**
> -     * @file
> -     *
> -     * @ingroup RTEMSScoreThread
> -     *
> -     * @brief @copybrief RTEMSScoreThread
> -     */
> +* This header file provides ... and so on.
> +
> +* This header file provides the API of the ABC Manager.
> +
> +* This header file provides interfaces and functions used to implement
> the XYZ
> +  Handler.
>

Again titles not sentences.

> +
> +For the ``@brief`` description of source files use phrases like this:
> +
> +* This source file contains the implementation of some_function().
> +
> +* This source file contains the definition of some_data_element.
> +
> +* This source file contains the implementation of XZY Hander functions
> related
> +  to ABC processing.
>

No.

>
>  .. code:: c
>
> @@ -99,38 +119,69 @@ from the corresponding group and omit the detailed
> description.
>       *
>       * @ingroup RTEMSScoreThread
>       *
> -     * @brief Some helpful brief description.
> -     *
> -     * Some helpful detailed description.
> +     * @brief This source file contains the implementation of
> +     *   _Thread_Initialize().
>       */
>

No.

>
>  Type Definitions
>  ----------------
>
> -Each type defined in a header file shall be documented with an ``@brief``
> -description and an optional detailed description.  Each type member shall
> be
> +Each type (``typedef``, ``struct``, ``enum``) defined in a header file
> shall be
>  documented with an ``@brief`` description and an optional detailed
> description.
> -Use grammatically correct sentences for the detailed descriptions.
> +Use grammatically correct sentences for the ``@brief`` and detailed
> +descriptions.
> +
> +For the ``@brief`` description of types use phrases like this:
> +
> +* This type represents ... and so on.
> +
> +* This structure represents ... and so on.
> +
> +* This structure provides ... and so on.
> +
> +* This enumeration represents ... and so on.
> +
> +* The XYZ represents ... and so on.
>

And so on. The @brief is not the first sentence of the description.


> +
> +Each type member shall be documented with an ``@brief`` description and an
> +optional detailed description.  Use grammatically correct sentences for
> the
> +``@brief`` and detailed descriptions.
> +
> +For the ``@brief`` description of types members use phrases like this:
> +
> +* This member represents ... and so on.
> +
> +* This member contains ... and so on.
> +
> +* This member references ... and so on.
> +
> +* The XYZ lock protects ... and so on.
> +
> +For the ``@brief`` description of boolean type members use a phrase like
> this:
> +"This member is true, if some condition is satisfied, otherwise it is
> false.".
>
>  .. code:: c
>
>      /**
> -     * @brief The information structure used to manage each API class of
> objects.
> +     * @brief The object information structure maintains the objects of an
> +     *   object class.
>       *
> -     * If objects for the API class are configured, an instance of this
> structure
> -     * is statically allocated and pre-initialized by
> OBJECTS_INFORMATION_DEFINE()
> -     * through <rtems/confdefs.h>.  The RTEMS library contains a
> statically
> -     * allocated and pre-initialized instance for each API class
> providing zero
> -     * objects, see OBJECTS_INFORMATION_DEFINE_ZERO().
> +     * If objects for the object class are configured, then an instance
> of this
> +     * structure is statically allocated and pre-initialized by
> +     * OBJECTS_INFORMATION_DEFINE() through <rtems/confdefs.h>.  The RTEMS
> +     * library contains a statically allocated and pre-initialized
> instance for
> +     * each object class providing zero objects, see
> +     * OBJECTS_INFORMATION_DEFINE_ZERO().
>       */
>      typedef struct {
>        /**
> -       * @brief This is the maximum valid ID of this object API class.
> +       * @brief This member contains the object identifier maximum of this
> +       *   object class.
>         *
> -       * This member is statically initialized and provides also the
> object API,
> -       * class and multiprocessing node information.
> +       * It is statically initialized.  The object identifier maximum
> provides
> +       * also the object API, class, and multiprocessing node information.
>         *
> -       * It is used by _Objects_Get() to validate an object ID.
> +       * It is used by _Objects_Get() to validate an object identifier.
>         */
>        Objects_Id maximum_id;
>
> @@ -140,27 +191,58 @@ Use grammatically correct sentences for the detailed
> descriptions.
>  Function Declarations
>  ---------------------
>
> -Each function declaration or function-like macros in a header file shall
> be
> +Each function declaration or function-like macro in a header file shall be
>  documented with an ``@brief`` description and an optional detailed
> description.
> -Use grammatically correct sentences for the brief and detailed
> descriptions.
> +Use grammatically correct sentences for the ``@brief`` and detailed
> +descriptions.  Use the descriptive-style for ``@brief`` descriptions, for
> +example ``"Creates a task."``, ``"Sends the events to the task."``, or
> +``"Obtains the semaphore."``.  Use "the" to refer to parameters of the
> +function.  Do not use descriptions like ``"Returns this and that."``.
> Describe
> +the function return in ``@retval`` and ``@return`` paragraphs.
> +
>  Each parameter shall be documented with an ``@param`` entry.  List the
>  ``@param`` entries in the order of the function parameters.  For
> *non-const
>  pointer* parameters
>
> -* use ``@param[out]``, if the referenced object is modified by the
> function, or
> +* use ``@param[out]``, if the function writes under some conditions to
> memory
> +  locations referenced directly or indirectly by the non-``const`` pointer
> +  parameter, or
> +
> +* use ``@param[in, out]``, if the function reads under some conditions
> from
> +  memory locations referenced directly or indirectly by the non-``const``
> +  pointer parameter and the function writes under some conditions to
> memory
> +  locations referenced directly or indirectly by the non-``const`` pointer
> +  parameter.
>
> -* use ``@param[in, out]``, if the referenced object is read and modified
> by the
> -  function.
> +If the function only reads from memory locations referenced directly or
> +indirectly by a non-``const`` pointer parameter, then the pointer
> parameter
> +should be made ``const``.
>
>  For other parameters (e.g. *const pointer* and *scalar* parameters) do
> not use
> -the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.  Each
> return
> -value or return value range shall be documented with an ``@retval`` entry.
> -Document the most common return value first.  Use a placeholder name for
> value
> -ranges, e.g. ``pointer`` in the ``_Workspace_Allocate()`` example below.
> In
> -case the function returns only one value, then use ``@return``, e.g. use
> -``@retval`` only if there are at least two return values or return value
> -ranges.  Use grammatically correct sentences for the parameter and return
> value
> -descriptions.
> +the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.
> +
> +For the ``@param`` descriptions use phrases like this:
> +
> +* is the ABC.
> +
> +* indicates what should be done.
> +
> +* defines the something.
> +
> +* references the object to deal with.
> +
> +The phrase shall form a grammatically correct sentence if "This parameter"
> +precedes the phrase, for example "This parameter is the size of the
> message in
> +bytes to send.".
> +
> +Distinctive return values shall be documented with an ``@retval`` entry.
> +Document the most common return value first.  Use ``@return`` to describe
> the
> +return of non-distinctive values.  Use grammatically correct sentences
> for the
> +descriptions.  Use sentences in simple past tense to describe conditions
> which
> +resulted in the return of a status value.  Place ``@retval`` descriptions
> +before the ``@return`` description.  For functions returning a boolean
> value,
> +use ``@return`` and a phrase like this: "Returns true, if some condition
> is
> +satisfied, otherwise false.".
>
>  .. code:: c
>
> @@ -231,12 +313,14 @@ descriptions.
>      /**
>       * @brief Allocates a memory block of the specified size from the
> workspace.
>       *
> -     * @param size The size of the memory block.
> +     * @param size is the size in bytes of the memory block.
>       *
> -     * @retval pointer The pointer to the memory block.  The pointer is
> at least
> -     *   aligned by CPU_HEAP_ALIGNMENT.
> -     * @retval NULL No memory block with the requested size is available
> in the
> +     * @retval NULL No memory block with the requested size was available
> in the
>       *   workspace.
> +     *
> +     * @return Returns the pointer to the allocated memory block, if
> enough
> +     *   memory to satisfy the allocation request was available.  The
> pointer is at
> +     *   least aligned by #CPU_HEAP_ALIGNMENT.
>       */
>      void *_Workspace_Allocate( size_t size );
>
> @@ -245,8 +329,8 @@ descriptions.
>      /**
>       * @brief Rebalances the red-black tree after insertion of the node.
>       *
> -     * @param[in, out] the_rbtree The red-black tree control.
> -     * @param[in, out] the_node The most recently inserted node.
> +     * @param[in, out] the_rbtree references the red-black tree.
> +     * @param[in, out] the_node references the most recently inserted
> node.
>       */
>      void _RBTree_Insert_color(
>        RBTree_Control *the_rbtree,
> @@ -258,12 +342,12 @@ descriptions.
>      /**
>       * @brief Builds an object ID from its components.
>       *
> -     * @param the_api The object API.
> -     * @param the_class The object API class.
> -     * @param node The object node.
> -     * @param index The object index.
> +     * @param the_api is the object API.
> +     * @param the_class is the object class.
> +     * @param node is the object node.
> +     * @param index is the object index.
>       *
> -     * @return Returns the object ID constructed from the arguments.
> +     * @return Returns the object ID built from the specified components.
>       */
>      #define _Objects_Build_id( the_api, the_class, node, index )
>
> diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst
> index caac2f7..3167670 100644
> --- a/eng/coding-file-hdr.rst
> +++ b/eng/coding-file-hdr.rst
> @@ -156,6 +156,8 @@ Use the following guidelines and template for C and
> C++ header files (here
>
>      #endif /* _FOO_BAR_BAZ_H */
>
> +.. _CCXXASMSourceFileTemplate:
> +
>  C/C++/Assembler Source File Template
>  ------------------------------------
>
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201109/1f25d8d8/attachment-0001.html>


More information about the devel mailing list