eng: Rework and clarify Doxygen Guidelines

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
+description.  Use grammatically correct sentences for the ``@brief`` and
-`Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_.
+detailed descriptions.
-Use grammatically correct sentences for the 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.
 
 .. 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.
      *
      * ...
      *
@@ -73,14 +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
+Each header and source file shall have an ``@file`` block at the top of the
-file.  The ``@file`` block should precede the license header separated by one
+file after the SPDX License Identifier.  The ``@file`` block shall precede the
-blank line.  This placement reduces the chance of merge conflicts in imported
+license header separated by one blank line, see :ref:`CCXXHeaderFileTemplate`
-third-party code.  The ``@file`` block shall be put into a group with
+and :ref:`CCXXASMSourceFileTemplate`.  The ``@file`` block shall be put into a
-``@ingroup GroupName``.  The ``@file`` block should have an ``@brief``
+group with ``@ingroup GroupName``.  The ``@file`` block shall have an
-description and a detailed description if it is considered helpful.  Use
+``@brief`` description and an optional detailed description.  The detailed
-``@brief @copybrief GroupName`` as a default to copy the ``@brief`` description
+description could give an explanation why a certain set of functions or data
-from the corresponding group and omit the detailed description.
+structures is grouped in one file.  Use grammatically correct sentences for the
+``@brief`` and detailed descriptions.
+
+For the ``@brief`` description of header files use phrases like this:
+
+* 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.
+
+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.
 
 .. code:: c
 
@@ -89,48 +119,69 @@ from the corresponding group and omit the detailed description.
      *
      * @ingroup RTEMSScoreThread
      *
-     * @brief @copybrief RTEMSScoreThread
+     * @brief This source file contains the implementation of
-     */
+     *   _Thread_Initialize().
-
-.. code:: c
-
-    /**
-     * @file
-     *
-     * @ingroup RTEMSScoreThread
-     *
-     * @brief Some helpful brief description.
-     *
-     * Some helpful detailed description.
      */
 
 Type Definitions
 ----------------
 
-Each type defined in a header file shall be documented with an ``@brief``
+Each type (``typedef``, ``struct``, ``enum``) defined in a header file shall be
-description and an optional detailed description.  Each type member 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.
+
+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
+     * If objects for the object class are configured, then an instance of this
-     * is statically allocated and pre-initialized by OBJECTS_INFORMATION_DEFINE()
+     * structure is statically allocated and pre-initialized by
-     * through <rtems/confdefs.h>.  The RTEMS library contains a statically
+     * OBJECTS_INFORMATION_DEFINE() through <rtems/confdefs.h>.  The RTEMS
-     * allocated and pre-initialized instance for each API class providing zero
+     * library contains a statically allocated and pre-initialized instance for
-     * objects, see OBJECTS_INFORMATION_DEFINE_ZERO().
+     * 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,
+       * It is statically initialized.  The object identifier maximum provides
-       * class and multiprocessing node information.
+       * 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 referenced object is read and modified by the
+* use ``@param[in, out]``, if the function reads under some conditions from
-  function.
+  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.
+
+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
+the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.
-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
+For the ``@param`` descriptions use phrases like this:
-ranges, e.g. ``pointer`` in the ``_Workspace_Allocate()`` example below.  In
+
-case the function returns only one value, then use ``@return``, e.g. use
+* is the ABC.
-``@retval`` only if there are at least two return values or return value
+
-ranges.  Use grammatically correct sentences for the parameter and return value
+* indicates what should be done.
-descriptions.
+
+* 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
+     * @retval NULL No memory block with the requested size was available in the
-     *   aligned by CPU_HEAP_ALIGNMENT.
-     * @retval NULL No memory block with the requested size is 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_rbtree references the red-black tree.
-     * @param[in, out] the_node The most recently inserted node.
+     * @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_api is the object API.
-     * @param the_class The object API class.
+     * @param the_class is the object class.
-     * @param node The object node.
+     * @param node is the object node.
-     * @param index The object index.
+     * @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 )
 

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
 ------------------------------------