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