mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-17 15:52:44 +08:00
eng: Rework and clarify Doxygen Guidelines
This commit is contained in:
Sebastian Huber
parent
bbd8d4a56f
commit
238789d8fa
@ -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,14 +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.
|
||||
|
||||
For the ``@brief`` description of header files use phrases like this:
|
||||
|
||||
* 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
|
||||
|
||||
@ -89,48 +119,69 @@ from the corresponding group and omit the detailed description.
|
||||
*
|
||||
* @ingroup RTEMSScoreThread
|
||||
*
|
||||
* @brief @copybrief RTEMSScoreThread
|
||||
*/
|
||||
|
||||
.. code:: c
|
||||
|
||||
/**
|
||||
* @file
|
||||
*
|
||||
* @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 referenced object is read and modified by the
|
||||
function.
|
||||
* 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.
|
||||
|
||||
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 )
|
||||
|
||||
|
||||
@ -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
|
||||
------------------------------------
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user