<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">---<br>
 eng/coding-doxygen.rst  | 210 ++++++++++++++++++++++++++++------------<br>
 eng/coding-file-hdr.rst |   2 +<br>
 2 files changed, 149 insertions(+), 63 deletions(-)<br>
<br>
diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst<br>
index f4308ef..b2e6b61 100644<br>
--- a/eng/coding-doxygen.rst<br>
+++ b/eng/coding-doxygen.rst<br>
@@ -16,12 +16,13 @@ In the RTEMS source code, CamelCase is rarely used, so this makes it easier to<br>
 search and replace Doxygen groups.  It avoids ambiguous references to<br>
 functions, types, defines, macros, and groups.  All groups shall have an<br>
 ``RTEMS`` prefix.  This makes it possible to include the RTEMS files with<br>
-Doxygen comments in a larger project without name conflicts.<br>
+Doxygen comments in a larger project without name conflicts.  The group name<br>
+shall use `Title Case <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a>>`_.<br>
<br>
 .. code:: c<br>
<br>
     /**<br>
-     * @defgroup RTEMSScoreThread<br>
+     * @defgroup RTEMSScoreThread Thread Handler<br>
      *<br>
      * @ingrop RTEMSScore<br>
      *<br>
@@ -36,18 +37,28 @@ global variable declaration shall belong to at least one Doxygen group.  Use<br>
 ``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets to add<br>
 members to a group.  A group shall be defined at most once.  Each group shall<br>
 be documented with an ``@brief`` description and an optional detailed<br>
-description.  The ``@brief`` description shall use<br>
-`Title Case <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a>>`_.<br>
-Use grammatically correct sentences for the detailed descriptions.<br>
+description.  Use grammatically correct sentences for the ``@brief`` and<br>
+detailed descriptions.<br>
+<br>
+For the ``@brief`` description use phrases like this:<br>
+<br>
+* This group contains ... and so on.<br>
+<br>
+* The XYZ Handler provides ... and so on.<br>
+<br>
+* The ABC Component contains ... and so on.<br></blockquote><div><br></div><div>I don't know where the idea @brief should be short sentences came from.</div><div>@brief is used to make table of contents type pages and those should</div><div>read more like titles than the first sentence of the detailed description.</div><div><br></div><div><a href="https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html">https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html</a><br></div><div><br></div><div>If you look at the PDF, it really is used for the Table of Contents and </div><div>a sentence is quite odd there. </div><div><br></div><div>It should read like a chapter title</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
 .. code:: c<br>
<br>
     /**<br>
-     * @defgroup RTEMSScoreThread<br>
+     * @defgroup RTEMSScoreThread Thread Handler<br>
      *<br>
      * @ingrop RTEMSScore<br>
      *<br>
-     * @brief Thread Handler<br>
+     * @brief The Thread Handler provides functionality related to the<br>
+     *   management of threads.<br>
+     *<br>
+     * This includes the creation, deletion, and scheduling of threads.<br></blockquote><div><br></div><div>No. The sentence you wrote would be better as the first sentence of the</div><div>description paragraph. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
      *<br>
      * ...<br>
      *<br>
@@ -73,24 +84,33 @@ Use grammatically correct sentences for the detailed descriptions.<br>
 Files<br>
 -----<br>
<br>
-Each source or header file shall have an ``@file`` block at the top of the<br>
-file.  The ``@file`` block should precede the license header separated by one<br>
-blank line.  This placement reduces the chance of merge conflicts in imported<br>
-third-party code.  The ``@file`` block shall be put into a group with<br>
-``@ingroup GroupName``.  The ``@file`` block should have an ``@brief``<br>
-description and a detailed description if it is considered helpful.  Use<br>
-``@brief @copybrief GroupName`` as a default to copy the ``@brief`` description<br>
-from the corresponding group and omit the detailed description.<br>
+Each header and source file shall have an ``@file`` block at the top of the<br>
+file after the SPDX License Identifier.  The ``@file`` block shall precede the<br>
+license header separated by one blank line, see :ref:`CCXXHeaderFileTemplate`<br>
+and :ref:`CCXXASMSourceFileTemplate`.  The ``@file`` block shall be put into a<br>
+group with ``@ingroup GroupName``.  The ``@file`` block shall have an<br>
+``@brief`` description and an optional detailed description.  The detailed<br>
+description could give an explanation why a certain set of functions or data<br>
+structures is grouped in one file.  Use grammatically correct sentences for the<br>
+``@brief`` and detailed descriptions.<br>
<br>
-.. code:: c<br>
+For the ``@brief`` description of header files use phrases like this:<br>
<br>
-    /**<br>
-     * @file<br>
-     *<br>
-     * @ingroup RTEMSScoreThread<br>
-     *<br>
-     * @brief @copybrief RTEMSScoreThread<br>
-     */<br>
+* This header file provides ... and so on.<br>
+<br>
+* This header file provides the API of the ABC Manager.<br>
+<br>
+* This header file provides interfaces and functions used to implement the XYZ<br>
+  Handler.<br></blockquote><div><br></div><div>Again titles not sentences. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+<br>
+For the ``@brief`` description of source files use phrases like this:<br>
+<br>
+* This source file contains the implementation of some_function().<br>
+<br>
+* This source file contains the definition of some_data_element.<br>
+<br>
+* This source file contains the implementation of XZY Hander functions related<br>
+  to ABC processing.<br></blockquote><div><br></div><div>No. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
 .. code:: c<br>
<br>
@@ -99,38 +119,69 @@ from the corresponding group and omit the detailed description.<br>
      *<br>
      * @ingroup RTEMSScoreThread<br>
      *<br>
-     * @brief Some helpful brief description.<br>
-     *<br>
-     * Some helpful detailed description.<br>
+     * @brief This source file contains the implementation of<br>
+     *   _Thread_Initialize().<br>
      */<br></blockquote><div><br></div><div>No. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
 Type Definitions<br>
 ----------------<br>
<br>
-Each type defined in a header file shall be documented with an ``@brief``<br>
-description and an optional detailed description.  Each type member shall be<br>
+Each type (``typedef``, ``struct``, ``enum``) defined in a header file shall be<br>
 documented with an ``@brief`` description and an optional detailed description.<br>
-Use grammatically correct sentences for the detailed descriptions.<br>
+Use grammatically correct sentences for the ``@brief`` and detailed<br>
+descriptions.<br>
+<br>
+For the ``@brief`` description of types use phrases like this:<br>
+<br>
+* This type represents ... and so on.<br>
+<br>
+* This structure represents ... and so on.<br>
+<br>
+* This structure provides ... and so on.<br>
+<br>
+* This enumeration represents ... and so on.<br>
+<br>
+* The XYZ represents ... and so on.<br></blockquote><div><br></div><div>And so on. The @brief is not the first sentence of the description.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+<br>
+Each type member shall be documented with an ``@brief`` description and an<br>
+optional detailed description.  Use grammatically correct sentences for the<br>
+``@brief`` and detailed descriptions.<br>
+<br>
+For the ``@brief`` description of types members use phrases like this:<br>
+<br>
+* This member represents ... and so on.<br>
+<br>
+* This member contains ... and so on.<br>
+<br>
+* This member references ... and so on.<br>
+<br>
+* The XYZ lock protects ... and so on.<br>
+<br>
+For the ``@brief`` description of boolean type members use a phrase like this:<br>
+"This member is true, if some condition is satisfied, otherwise it is false.".<br>
<br>
 .. code:: c<br>
<br>
     /**<br>
-     * @brief The information structure used to manage each API class of objects.<br>
+     * @brief The object information structure maintains the objects of an<br>
+     *   object class.<br>
      *<br>
-     * If objects for the API class are configured, an instance of this structure<br>
-     * is statically allocated and pre-initialized by OBJECTS_INFORMATION_DEFINE()<br>
-     * through <rtems/confdefs.h>.  The RTEMS library contains a statically<br>
-     * allocated and pre-initialized instance for each API class providing zero<br>
-     * objects, see OBJECTS_INFORMATION_DEFINE_ZERO().<br>
+     * If objects for the object class are configured, then an instance of this<br>
+     * structure is statically allocated and pre-initialized by<br>
+     * OBJECTS_INFORMATION_DEFINE() through <rtems/confdefs.h>.  The RTEMS<br>
+     * library contains a statically allocated and pre-initialized instance for<br>
+     * each object class providing zero objects, see<br>
+     * OBJECTS_INFORMATION_DEFINE_ZERO().<br>
      */<br>
     typedef struct {<br>
       /**<br>
-       * @brief This is the maximum valid ID of this object API class.<br>
+       * @brief This member contains the object identifier maximum of this<br>
+       *   object class.<br>
        *<br>
-       * This member is statically initialized and provides also the object API,<br>
-       * class and multiprocessing node information.<br>
+       * It is statically initialized.  The object identifier maximum provides<br>
+       * also the object API, class, and multiprocessing node information.<br>
        *<br>
-       * It is used by _Objects_Get() to validate an object ID.<br>
+       * It is used by _Objects_Get() to validate an object identifier.<br>
        */<br>
       Objects_Id maximum_id;<br>
<br>
@@ -140,27 +191,58 @@ Use grammatically correct sentences for the detailed descriptions.<br>
 Function Declarations<br>
 ---------------------<br>
<br>
-Each function declaration or function-like macros in a header file shall be<br>
+Each function declaration or function-like macro in a header file shall be<br>
 documented with an ``@brief`` description and an optional detailed description.<br>
-Use grammatically correct sentences for the brief and detailed descriptions.<br>
+Use grammatically correct sentences for the ``@brief`` and detailed<br>
+descriptions.  Use the descriptive-style for ``@brief`` descriptions, for<br>
+example ``"Creates a task."``, ``"Sends the events to the task."``, or<br>
+``"Obtains the semaphore."``.  Use "the" to refer to parameters of the<br>
+function.  Do not use descriptions like ``"Returns this and that."``.  Describe<br>
+the function return in ``@retval`` and ``@return`` paragraphs.<br>
+<br>
 Each parameter shall be documented with an ``@param`` entry.  List the<br>
 ``@param`` entries in the order of the function parameters.  For *non-const<br>
 pointer* parameters<br>
<br>
-* use ``@param[out]``, if the referenced object is modified by the function, or<br>
+* use ``@param[out]``, if the function writes under some conditions to memory<br>
+  locations referenced directly or indirectly by the non-``const`` pointer<br>
+  parameter, or<br>
+<br>
+* use ``@param[in, out]``, if the function reads under some conditions from<br>
+  memory locations referenced directly or indirectly by the non-``const``<br>
+  pointer parameter and the function writes under some conditions to memory<br>
+  locations referenced directly or indirectly by the non-``const`` pointer<br>
+  parameter.<br>
<br>
-* use ``@param[in, out]``, if the referenced object is read and modified by the<br>
-  function.<br>
+If the function only reads from memory locations referenced directly or<br>
+indirectly by a non-``const`` pointer parameter, then the pointer parameter<br>
+should be made ``const``.<br>
<br>
 For other parameters (e.g. *const pointer* and *scalar* parameters) do not use<br>
-the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.  Each return<br>
-value or return value range shall be documented with an ``@retval`` entry.<br>
-Document the most common return value first.  Use a placeholder name for value<br>
-ranges, e.g. ``pointer`` in the ``_Workspace_Allocate()`` example below.  In<br>
-case the function returns only one value, then use ``@return``, e.g. use<br>
-``@retval`` only if there are at least two return values or return value<br>
-ranges.  Use grammatically correct sentences for the parameter and return value<br>
-descriptions.<br>
+the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.<br>
+<br>
+For the ``@param`` descriptions use phrases like this:<br>
+<br>
+* is the ABC.<br>
+<br>
+* indicates what should be done.<br>
+<br>
+* defines the something.<br>
+<br>
+* references the object to deal with.<br>
+<br>
+The phrase shall form a grammatically correct sentence if "This parameter"<br>
+precedes the phrase, for example "This parameter is the size of the message in<br>
+bytes to send.".<br>
+<br>
+Distinctive return values shall be documented with an ``@retval`` entry.<br>
+Document the most common return value first.  Use ``@return`` to describe the<br>
+return of non-distinctive values.  Use grammatically correct sentences for the<br>
+descriptions.  Use sentences in simple past tense to describe conditions which<br>
+resulted in the return of a status value.  Place ``@retval`` descriptions<br>
+before the ``@return`` description.  For functions returning a boolean value,<br>
+use ``@return`` and a phrase like this: "Returns true, if some condition is<br>
+satisfied, otherwise false.".<br>
<br>
 .. code:: c<br>
<br>
@@ -231,12 +313,14 @@ descriptions.<br>
     /**<br>
      * @brief Allocates a memory block of the specified size from the workspace.<br>
      *<br>
-     * @param size The size of the memory block.<br>
+     * @param size is the size in bytes of the memory block.<br>
      *<br>
-     * @retval pointer The pointer to the memory block.  The pointer is at least<br>
-     *   aligned by CPU_HEAP_ALIGNMENT.<br>
-     * @retval NULL No memory block with the requested size is available in the<br>
+     * @retval NULL No memory block with the requested size was available in the<br>
      *   workspace.<br>
+     *<br>
+     * @return Returns the pointer to the allocated memory block, if enough<br>
+     *   memory to satisfy the allocation request was available.  The pointer is at<br>
+     *   least aligned by #CPU_HEAP_ALIGNMENT.<br>
      */<br>
     void *_Workspace_Allocate( size_t size );<br>
<br>
@@ -245,8 +329,8 @@ descriptions.<br>
     /**<br>
      * @brief Rebalances the red-black tree after insertion of the node.<br>
      *<br>
-     * @param[in, out] the_rbtree The red-black tree control.<br>
-     * @param[in, out] the_node The most recently inserted node.<br>
+     * @param[in, out] the_rbtree references the red-black tree.<br>
+     * @param[in, out] the_node references the most recently inserted node.<br>
      */<br>
     void _RBTree_Insert_color(<br>
       RBTree_Control *the_rbtree,<br>
@@ -258,12 +342,12 @@ descriptions.<br>
     /**<br>
      * @brief Builds an object ID from its components.<br>
      *<br>
-     * @param the_api The object API.<br>
-     * @param the_class The object API class.<br>
-     * @param node The object node.<br>
-     * @param index The object index.<br>
+     * @param the_api is the object API.<br>
+     * @param the_class is the object class.<br>
+     * @param node is the object node.<br>
+     * @param index is the object index.<br>
      *<br>
-     * @return Returns the object ID constructed from the arguments.<br>
+     * @return Returns the object ID built from the specified components.<br>
      */<br>
     #define _Objects_Build_id( the_api, the_class, node, index )<br>
<br>
diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst<br>
index caac2f7..3167670 100644<br>
--- a/eng/coding-file-hdr.rst<br>
+++ b/eng/coding-file-hdr.rst<br>
@@ -156,6 +156,8 @@ Use the following guidelines and template for C and C++ header files (here<br>
<br>
     #endif /* _FOO_BAR_BAZ_H */<br>
<br>
+.. _CCXXASMSourceFileTemplate:<br>
+<br>
 C/C++/Assembler Source File Template<br>
 ------------------------------------<br>
<br>
-- <br>
2.26.2<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>