From 131175d899356683fd9731c58d46ca3281483038 Mon Sep 17 00:00:00 2001 From: Daniel Oliveira Date: Fri, 17 Mar 2023 12:08:00 +0000 Subject: [PATCH] ref(code-doc): change the writing of doxygen generic guidelines Signed-off-by: Daniel Oliveira --- source/development/code_documentation.rst | 37 ++++++++++++----------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/source/development/code_documentation.rst b/source/development/code_documentation.rst index 1451354..a87901d 100644 --- a/source/development/code_documentation.rst +++ b/source/development/code_documentation.rst @@ -30,32 +30,33 @@ repositories. Doxygen Generic Guidelines -------------------------- -Although this tutorial is focused on defining guidelines to apply the doxygen -tags to Bao's functions and data structures, there are some elemental rules -that must be followed for all doxygen comments: +While this tutorial primarily provides guidelines for applying Doxygen tags to +code functions and data structures, there are some fundamental rules that +**must** apply to all Doxygen comments: -* Block comments shall **start** with ``/**`` (slash-asterisk-asterisk) +* Block comments **must** start with ``/**`` (slash-asterisk-asterisk) in a single line. -* Block comments shall **end** with ``*/`` (space-asterisk-slash) in a +* Block comments **must** end with ``*/`` (space-asterisk-slash) in a single line. -* Every other line inside the comment block shall start with ``*`` - (space-asterisk). -* Each different group tag (``@brief``, ``@param``, ...) shall be in at least - one line. In other words, it is not possible to have two tags on the same - line. -* All doxygen comments must be indented to the same level as the item they are - describing. - -On the beginning of every file there must be the mandatory license (SPDX -license identifier) before the file Doxygen block comment. - -Example for the generic guidelines: +* Every other line inside the comment block **must** start with + ``*`` (space-asterisk). +* Each different tag (``@brief``, ``@param``, ...) **must** be in a + a separate line. +* All doxygen comments **must** be indented to the same level as the item they + are describing. +* All APIS **must** be commented with doxygen tags, except for private/static + functions, which is optional. + +As stated in the :ref:`licensing guidelines `, every file must start +with a header comment including an SPDX license identifier and copyright +statement. All doxygen block comments, including the **file** brief, must be +placed after this header.Example for the generic guidelines: .. code-block:: c /** * @brief Brief description of the function, struct, enum,... - * @param Paremeter_1 parameter_1 description + * @param Parameter_1 parameter_1 description * @param Parameter_2 parameter_2 description * @return return description */