[PATCH] eng: Rework and clarify Doxygen Guidelines
Joel Sherrill
joel at rtems.org
Mon Nov 9 14:12:16 UTC 2020
On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber <
sebastian.huber at 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 at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201109/1f25d8d8/attachment-0001.html>
More information about the devel
mailing list