From 2dd21c199eca12ed2ffd2a4ff711ee7315b7b17d Mon Sep 17 00:00:00 2001 From: Rodrigo Caballero Date: Fri, 3 Jul 2015 14:56:30 -0500 Subject: [PATCH] Doc: Edit to the Doxygen guidelines based on feedback. Added a asterisk in front of every line of the comments to fully comply with the Javadoc style. Updated all cross-references to comply with the new style. Added a note indicating explicitly that enums are to be documented just as structs. Change-Id: If017e14e3e478ec28befb5c1fcae92090f91c32e Signed-off-by: Rodrigo Caballero --- doc/documentation/rest_cross.rst | 3 +- doc/doxygen/doxygen_guidelines.rst | 19 +++--- doc/doxygen/doxygen_guidelines_defines.rst | 20 +++--- doc/doxygen/doxygen_guidelines_files.rst | 11 ++-- doc/doxygen/doxygen_guidelines_functions.rst | 6 +- doc/doxygen/doxygen_guidelines_structs.rst | 7 +- doc/doxygen/doxygen_guidelines_typedefs.rst | 2 +- doc/doxygen/doxygen_guidelines_variables.rst | 2 +- doc/doxygen/hello_commented.c | 68 ++++++++++---------- doc/doxygen/phil_commented.h | 10 +-- 10 files changed, 76 insertions(+), 72 deletions(-) diff --git a/doc/documentation/rest_cross.rst b/doc/documentation/rest_cross.rst index db84e3f8bb3..9a48c3c03d5 100644 --- a/doc/documentation/rest_cross.rst +++ b/doc/documentation/rest_cross.rst @@ -110,8 +110,7 @@ reference to a documented code element. .. caution:: References to in-code documentation only work if the element has been - documented in the code following the :ref:`In-Code Documentation - Guidelines`. + documented in the code following the :ref:`code_documentation_guidelines`. External References =================== diff --git a/doc/doxygen/doxygen_guidelines.rst b/doc/doxygen/doxygen_guidelines.rst index c1bad718426..92064966016 100644 --- a/doc/doxygen/doxygen_guidelines.rst +++ b/doc/doxygen/doxygen_guidelines.rst @@ -1,23 +1,24 @@ -.. _In-Code Documentation Guidelines: +.. _code_documentation_guidelines: In-Code Documentation Guidelines ################################ -Follow these guidelines to document your code using comments. We -provide examples on how to comment different parts of the code. Files, -functions, defines, structures, variables and type definitions must be -documented. +Follow these guidelines to document your code using comments. The |project| +follows the Javadoc Doxygen comments style. We provide examples on how to +comment different parts of the code. Files, functions, defines, structures, +variables and type definitions must be documented. We have grouped the guidelines according to the object that is being -documented. Read the information regarding all elements carefully since -each type of object provides further details as to how to document the -code as a whole. +documented. Read sections carefully since each object provides further +details as to how to document the code as a whole. These simple rules apply to all the code that you wish to include in the documentation: #. Start and end a comment block with :literal:`/**` and :literal:`*/` +#. Start each line of the comment with :literal:` * ` + #. Use \@ for all Doxygen special commands. #. Files, functions, defines, structures, variables and type @@ -26,7 +27,7 @@ the documentation: #. All comments must start with a capital letter and end in a period. Even if the comment is a sentence fragment. -.. important:: +.. note:: Always use :literal:`/**` This is a comment. :literal:`*/` if that comment should become part of the documentation. diff --git a/doc/doxygen/doxygen_guidelines_defines.rst b/doc/doxygen/doxygen_guidelines_defines.rst index 2198a2901e6..56a22a3e4d0 100644 --- a/doc/doxygen/doxygen_guidelines_defines.rst +++ b/doc/doxygen/doxygen_guidelines_defines.rst @@ -1,4 +1,4 @@ -.. _Define Documentation: +.. _define_documentation: Define Documentation #################### @@ -23,11 +23,11 @@ Full template: .. code-block:: c /** @def name_of_define - - @brief Brief description of the define. - - @details Multiple lines describing in detail what is the - purpose of the define and what it does. + * + * @brief Brief description of the define. + * + * @details Multiple lines describing in detail what is the + * purpose of the define and what it does. */ #define name_of_define @@ -37,10 +37,10 @@ Simplified template: .. code-block:: c /** - Brief description of the define. - - Multiple lines describing in detail what is the - purpose of the define and what it does. + * Brief description of the define. + * + * Multiple lines describing in detail what is the + * purpose of the define and what it does. */ #define name_of_define diff --git a/doc/doxygen/doxygen_guidelines_files.rst b/doc/doxygen/doxygen_guidelines_files.rst index 370ae79a27e..52c5cee2382 100644 --- a/doc/doxygen/doxygen_guidelines_files.rst +++ b/doc/doxygen/doxygen_guidelines_files.rst @@ -1,4 +1,4 @@ -.. _File Header Documentation: +.. _file_header_documentation: File Header Documentation ######################### @@ -16,13 +16,14 @@ beginning of the file. The file header must contain: purpose of the file, how it works and any other pertinent information such as copyrights, authors, etc. -.. note:: +.. note:: Doxygen has special commands for copyrights (@copyright), authors (@author), and other important information. Please refer to the `Doxygen documentation`_ for further details. - -.. _Doxygen documentation: http://www.stack.nl/~dimitri/doxygen/manual/index.html + +.. _Doxygen documentation: + http://www.stack.nl/~dimitri/doxygen/manual/index.html Examples ******** @@ -31,8 +32,6 @@ Correct: * A file header with a single line description. - - .. literalinclude:: hello_commented.c :language: c :lines: 1-5 diff --git a/doc/doxygen/doxygen_guidelines_functions.rst b/doc/doxygen/doxygen_guidelines_functions.rst index b2f910e3bc0..e99bb62789b 100644 --- a/doc/doxygen/doxygen_guidelines_functions.rst +++ b/doc/doxygen/doxygen_guidelines_functions.rst @@ -1,4 +1,4 @@ -.. _Function Documentation: +.. _function_documentation: Function Documentation ###################### @@ -61,7 +61,7 @@ Simplified template: my_function(int a, int b){} .. important:: - Ensure that there is **no** blank line between the comment block + Ensure that there is **no** blank line between the comment block and the function's signature. That way Doxygen can link the comment to the function. @@ -83,7 +83,7 @@ The highlighted lines show comments that would not be added to the documentation. That is unacceptable. The appropriate way to document :c:func:`taskA()` is: -.. literalinclude:: hello_commented.c +.. literalinclude:: hello_commented.c :language: c :lines: 97-110 :emphasize-lines: 5-7, 11, 13 diff --git a/doc/doxygen/doxygen_guidelines_structs.rst b/doc/doxygen/doxygen_guidelines_structs.rst index 1037fc14b2b..aff70d628a4 100644 --- a/doc/doxygen/doxygen_guidelines_structs.rst +++ b/doc/doxygen/doxygen_guidelines_structs.rst @@ -1,4 +1,4 @@ -.. _Structure Documentation: +.. _structure_documentation: Structure Documentation ####################### @@ -9,6 +9,11 @@ structs only require a brief description detailing why they are needed. Each variable that composes a struct must be commented. A fully simplified syntax is therefore appropriate. +.. note:: + + Follow the same rules as struct when documenting an enum. Use the + simplified syntax to add the brief description. + Structure Comments Template *************************** Structs only have a simplified template: diff --git a/doc/doxygen/doxygen_guidelines_typedefs.rst b/doc/doxygen/doxygen_guidelines_typedefs.rst index 777604ba8b6..0dc81f018c3 100644 --- a/doc/doxygen/doxygen_guidelines_typedefs.rst +++ b/doc/doxygen/doxygen_guidelines_typedefs.rst @@ -1,4 +1,4 @@ -.. _Type Definition Documentation: +.. _type_definition_documentation: Type Definition Documentation ############################# diff --git a/doc/doxygen/doxygen_guidelines_variables.rst b/doc/doxygen/doxygen_guidelines_variables.rst index a9f5afd7252..54ee89d8356 100644 --- a/doc/doxygen/doxygen_guidelines_variables.rst +++ b/doc/doxygen/doxygen_guidelines_variables.rst @@ -1,4 +1,4 @@ -.. _Variable Documentation: +.. _variable_documentation: Variable Documentation ###################### diff --git a/doc/doxygen/hello_commented.c b/doc/doxygen/hello_commented.c index b82ca47e6a1..a88b5b0deda 100644 --- a/doc/doxygen/hello_commented.c +++ b/doc/doxygen/hello_commented.c @@ -46,12 +46,12 @@ */ /** - @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) - @brief Compute equivalence in ticks. + * @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) + * @brief Compute equivalence in ticks. */ /** - @def SLEEPTIME - @brief Specify delay between greetings (in ms). + * @def SLEEPTIME + * @brief Specify delay between greetings (in ms). */ #if defined(CONFIG_STDOUT_CONSOLE) @@ -70,12 +70,12 @@ #define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) /** - @brief A loop saying hello. - - @details - Actions: - -# Ouputs "Hello World!". - -# Waits, then lets another task run. + * @brief A loop saying hello. + * + * @details + * Actions: + * -# Ouputs "Hello World!". + * -# Waits, then lets another task run. @param taskname The task's identification string. @param mySem The task's semaphore. @@ -95,12 +95,12 @@ void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem) } /** - @brief Exchanges Hello messages with taskB. - - @details - Actions: - -# taskA gives its own semaphore, thus it says hello right away. - -# Calls function helloLoop, thus taskA exchanges hello messages with taskB. + * @brief Exchanges Hello messages with taskB. + * + * @details + * Actions: + * -# taskA gives its own semaphore, thus it says hello right away. + * -# Calls function helloLoop, thus taskA exchanges hello messages with taskB. */ void taskA(void) { @@ -110,10 +110,10 @@ void taskA(void) } /** - @brief Exchanges Hello messages with taskA. - - Actions: - -# Calls function helloLoop, thus taskB exchanges hello messages with taskA. + * @brief Exchanges Hello messages with taskA. + * + * Actions: + * -# Calls function helloLoop, thus taskB exchanges hello messages with taskA. */ void taskB(void) { @@ -140,14 +140,14 @@ struct nano_sem nanoSemTask; struct nano_sem nanoSemFiber; /** - @brief Defines the turns taken by the tasks in the fiber. - - Actions: - -# Initializes semaphore. - -# Initializes timer. - -# Waits for task, then runs. - -# Outputs "Hello World!". - -# Waits, then yields to another task. + * @brief Defines the turns taken by the tasks in the fiber. + * + * Actions: + * -# Initializes semaphore. + * -# Initializes timer. + * -# Waits for task, then runs. + * -# Outputs "Hello World!". + * -# Waits, then yields to another task. */ void fiberEntry(void) { struct nano_timer timer; @@ -170,12 +170,12 @@ void fiberEntry(void) { } /** - @brief Implements the Hello demo. - - Actions: - -# Outputs "hello". - -# Waits, then signals fiber's semaphore. - -# Waits on fiber to yield. + * @brief Implements the Hello demo. + * + * Actions: + * -# Outputs "hello". + * -# Waits, then signals fiber's semaphore. + * -# Waits on fiber to yield. */ void main(void) { struct nano_timer timer; diff --git a/doc/doxygen/phil_commented.h b/doc/doxygen/phil_commented.h index c229693b168..ff9e1a84339 100644 --- a/doc/doxygen/phil_commented.h +++ b/doc/doxygen/phil_commented.h @@ -44,11 +44,11 @@ #endif /** - @def N_PHILOSOPHERS - @brief Defines the number of philosophers. - -@details Multiple tasks do printfs and they may conflict. -Uses puts() instead of printf() to avoid conflicts. + * @def N_PHILOSOPHERS + * @brief Defines the number of philosophers. + * + * @details Multiple tasks do printfs and they may conflict. + * Uses puts() instead of printf() to avoid conflicts. */ #define N_PHILOSOPHERS 6