On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber < sebastian.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
