eng: Rework and clarify Doxygen Guidelines

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.
 
 .. 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,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.
+
+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
 
@@ -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().
      */
 
 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.
+
+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
 ------------------------------------