diff --git a/doc/doxygen/doxygen_guidelines.rst b/doc/doxygen/doxygen_guidelines.rst index 0422e7c2c2f..c1bad718426 100644 --- a/doc/doxygen/doxygen_guidelines.rst +++ b/doc/doxygen/doxygen_guidelines.rst @@ -3,8 +3,8 @@ 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, +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. @@ -13,10 +13,10 @@ 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. -These simple rules apply to all the code that you wish to include in the -documentation: +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 and end a comment block with :literal:`/**` and :literal:`*/` #. Use \@ for all Doxygen special commands. @@ -28,14 +28,15 @@ documentation: .. important:: - Always use :literal:`/*!` This is a comment. :literal:`*/` if that comment should - become part of the documentation. - Use :literal:`/*` This comment won't appear in the documentation :literal:`*/` for - comments that you want in the code but not in the documentation. + Always use :literal:`/**` This is a comment. :literal:`*/` if that + comment should become part of the documentation. + Use :literal:`/*` This comment won't appear in the documentation : + literal:`*/` for comments that you want in the code but not in the + documentation. .. toctree:: :maxdepth: 2 - + doxygen_guidelines_files.rst doxygen_guidelines_functions.rst doxygen_guidelines_variables.rst diff --git a/doc/doxygen/doxygen_guidelines_defines.rst b/doc/doxygen/doxygen_guidelines_defines.rst index c473bf2b7ee..2198a2901e6 100644 --- a/doc/doxygen/doxygen_guidelines_defines.rst +++ b/doc/doxygen/doxygen_guidelines_defines.rst @@ -22,7 +22,7 @@ Full template: .. code-block:: c - /*! @def name_of_define + /** @def name_of_define @brief Brief description of the define. @@ -36,7 +36,7 @@ Simplified template: .. code-block:: c - /*! + /** Brief description of the define. Multiple lines describing in detail what is the @@ -71,6 +71,6 @@ Incorrect: :linenos: Observe that the comment does not start with -:literal:`/*!` and therefore Doxygen will ignore it. +:literal:`/**` and therefore Doxygen will ignore it. The comment is ambiguous; it could apply to either the define or the #if. \ No newline at end of file diff --git a/doc/doxygen/doxygen_guidelines_functions.rst b/doc/doxygen/doxygen_guidelines_functions.rst index 16da48baf64..b2f910e3bc0 100644 --- a/doc/doxygen/doxygen_guidelines_functions.rst +++ b/doc/doxygen/doxygen_guidelines_functions.rst @@ -22,7 +22,7 @@ Full template: .. code-block:: c - /*! + /** * @brief Short description of my_function(). * * @details Longer multi-paragraph description. @@ -46,7 +46,7 @@ Simplified template: .. code-block:: c - /*! + /** * Short description of my_function(). * * Longer multi-paragraph description. @@ -107,7 +107,7 @@ Take the more complex function hello_loop(): The function parameters have been documented using the correct Doxygen command but notice line 1. The comment block was not started with -:literal:`/*!` and therefore Doxygen won't parse it correctly. +:literal:`/**` and therefore Doxygen won't parse it correctly. The parameters have been documented using the \\param command. This is equivalent to using @param but incorrect according to these guidelines. diff --git a/doc/doxygen/doxygen_guidelines_structs.rst b/doc/doxygen/doxygen_guidelines_structs.rst index 0c98b7172fb..1037fc14b2b 100644 --- a/doc/doxygen/doxygen_guidelines_structs.rst +++ b/doc/doxygen/doxygen_guidelines_structs.rst @@ -34,7 +34,7 @@ Correct: :linenos: Make sure to start every comment with -:literal:`/*!` and end it with :literal:`*/`. Every comment must start +:literal:`/**` and end it with :literal:`*/`. Every comment must start with a capital letter and end with a period. Doxygen requires that line 6 is left blank. Ensure a blank line diff --git a/doc/doxygen/doxygen_guidelines_typedefs.rst b/doc/doxygen/doxygen_guidelines_typedefs.rst index 273230b4e28..777604ba8b6 100644 --- a/doc/doxygen/doxygen_guidelines_typedefs.rst +++ b/doc/doxygen/doxygen_guidelines_typedefs.rst @@ -16,7 +16,7 @@ what type they are referencing. .. code-block:: c - /*! Brief description with the type that is being used and why. */ + /** Brief description with the type that is being used and why. */ typedef int t_ie; No further explanation is needed regarding the type even if it is @@ -51,6 +51,6 @@ Incorrect: The comments on lines 3 and 4 offer little insight into the code's behavior. Furthermore, they do not start with -:literal:`/*!` and end with :literal:`*/`. Doxygen won't add the +:literal:`/**` and end with :literal:`*/`. Doxygen won't add the information to the documentation nor link it properly to the complex type documentation. \ No newline at end of file diff --git a/doc/doxygen/doxygen_guidelines_variables.rst b/doc/doxygen/doxygen_guidelines_variables.rst index 51baf977840..a9f5afd7252 100644 --- a/doc/doxygen/doxygen_guidelines_variables.rst +++ b/doc/doxygen/doxygen_guidelines_variables.rst @@ -15,7 +15,7 @@ Variable Comment Template .. code-block:: c - /*! Brief description of singificant_variable's purpose. */ + /** Brief description of singificant_variable's purpose. */ int significant_variable; Variable Documentation Examples @@ -60,7 +60,7 @@ Variables outside of functions have to be documented as well. :linenos: As you can see the syntax of the comment does not change. Always start -the comment with :literal:`/*!` and end it with :literal:`*/`. Remember +the comment with :literal:`/**` and end it with :literal:`*/`. Remember to begin with a capital letter and end with a period, even if the comment is only a sentence fragment. diff --git a/doc/doxygen/ex_struct_pre.c b/doc/doxygen/ex_struct_pre.c index e81bcd38785..b61a3b65895 100644 --- a/doc/doxygen/ex_struct_pre.c +++ b/doc/doxygen/ex_struct_pre.c @@ -1,11 +1,11 @@ -/*! @brief Brief description of struct pre. +/** @brief Brief description of struct pre. * * Detailed description of struct pre. Optional * */ struct pre { - /*! Variable g brief description. */ + /** Variable g brief description. */ int g; - /*! Variable h brief description. */ + /** Variable h brief description. */ int h; }; diff --git a/doc/doxygen/hello_commented.c b/doc/doxygen/hello_commented.c index 3a7949e99fc..b82ca47e6a1 100644 --- a/doc/doxygen/hello_commented.c +++ b/doc/doxygen/hello_commented.c @@ -1,7 +1,7 @@ -/*! @file +/** @file @brief Hello World Demo - A Hello World demo for the Nanokernel and the Microkernel. + A Hello World demo for the Nanokernel and the Microkernel. */ /* @@ -34,22 +34,22 @@ * POSSIBILITY OF SUCH DAMAGE. */ -/*! CONFIG_MICROKERNEL +/** CONFIG_MICROKERNEL The microkernel hello world demo has two tasks that use semaphores - and sleeps to take turns printing a greeting message at a + and sleeps to take turns printing a greeting message at a controlled rate.*/ -/*! #else || CONFIG_NANOKERNEL +/** #else || CONFIG_NANOKERNEL * The nanokernel hello world demo has a task and a fiber that use * semaphores and timers to take turns printing a greeting message at * a controlled rate. */ -/*! +/** @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) @brief Compute equivalence in ticks. */ -/*! +/** @def SLEEPTIME @brief Specify delay between greetings (in ms). */ @@ -67,15 +67,15 @@ #include #define SLEEPTIME 500 -#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) +#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. + -# Waits, then lets another task run. @param taskname The task's identification string. @param mySem The task's semaphore. @@ -94,7 +94,7 @@ void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem) } } -/*! +/** @brief Exchanges Hello messages with taskB. @details @@ -109,7 +109,7 @@ void taskA(void) helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */ } -/*! +/** @brief Exchanges Hello messages with taskA. Actions: @@ -120,26 +120,26 @@ void taskB(void) helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */ } -#else +#else #include #include -#define SLEEPTIME 500 +#define SLEEPTIME 500 #define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) #define STACKSIZE 2000 -/*! Declares a stack for a fiber with a size of 2000.*/ +/** Declares a stack for a fiber with a size of 2000.*/ char fiberStack[STACKSIZE]; -/*! Declares a nanokernel semaphore for a task. */ +/** Declares a nanokernel semaphore for a task. */ struct nano_sem nanoSemTask; -/*! Declares a nanokernel semaphore for a fiber.*/ +/** Declares a nanokernel semaphore for a fiber.*/ struct nano_sem nanoSemFiber; -/*! +/** @brief Defines the turns taken by the tasks in the fiber. Actions: @@ -169,7 +169,7 @@ void fiberEntry(void) { } } -/*! +/** @brief Implements the Hello demo. Actions: @@ -199,5 +199,4 @@ void main(void) { } } -#endif - +#endif \ No newline at end of file diff --git a/doc/doxygen/irq_test_common_commented.h b/doc/doxygen/irq_test_common_commented.h index fba5a139378..5de651313fb 100644 --- a/doc/doxygen/irq_test_common_commented.h +++ b/doc/doxygen/irq_test_common_commented.h @@ -65,10 +65,10 @@ Interrupt stuff, abstracted across CPU architectures. #endif /* NUM_SW_IRQS >= 2 */ #endif -/*! Declares a void-void function pointer to test the ISR. */ +/** Declares a void-void function pointer to test the ISR. */ typedef void (*vvfn)(void); -/*! Declares a void-void_pointer function pointer to test the ISR. */ +/** Declares a void-void_pointer function pointer to test the ISR. */ typedef void (*vvpfn)(void *); #if defined(CONFIG_X86_32) @@ -113,13 +113,13 @@ static inline void sw_isr_trigger_1(void) #endif /* CONFIG_CPU_CORTEX_M */ #endif -/*! Defines the ISR initialization information. */ +/** Defines the ISR initialization information. */ struct isrInitInfo { - /*! Declares the void-void function pointer for the ISR. */ + /** Declares the void-void function pointer for the ISR. */ vvpfn isr[2]; - /*! Declares a space for the information. */ + /** Declares a space for the information. */ void *arg[2]; }; diff --git a/doc/doxygen/phil_commented.h b/doc/doxygen/phil_commented.h index 30006da4f82..c229693b168 100644 --- a/doc/doxygen/phil_commented.h +++ b/doc/doxygen/phil_commented.h @@ -1,4 +1,4 @@ -/*! @file +/** @file * @brief Dining philosophers header file. * * Collects the includes and defines needed to implement the dining philosophers @@ -43,7 +43,7 @@ #include #endif -/*! +/** @def N_PHILOSOPHERS @brief Defines the number of philosophers. diff --git a/doc/doxygen/phil_fiber_commented.c b/doc/doxygen/phil_fiber_commented.c index 15d996e1991..8fd802474b1 100644 --- a/doc/doxygen/phil_fiber_commented.c +++ b/doc/doxygen/phil_fiber_commented.c @@ -1,4 +1,4 @@ -/*! @file +/** @file * @brief Solution to the dining philosophers problem using fibers. */ @@ -69,7 +69,7 @@ kmutex_t forks[] = { forkMutex0, forkMutex1, forkMutex2, forkMutex3, forkMutex4, forkMutex5 }; #endif -/*! +/** * @brief Prints a philosopher's state. * * @param id A philosopher's ID. @@ -83,7 +83,7 @@ static void myPrint(int id, PRINTF("\x1b[%d;%dHPhilosopher %d %s\n", id + 1, 1, id, str); } -/*! +/** * @brief Waits for a number of ticks to elapse. * * @param ticks Number of ticks to delay. @@ -103,7 +103,7 @@ static void myDelay(int ticks #endif } -/*! +/** * @brief Entry point to a philosopher's thread. * * @details This routine runs as a task in the microkernel environment @@ -117,23 +117,23 @@ static void myDelay(int ticks */ void philEntry(void) { #ifdef CONFIG_NANOKERNEL - /*! Declares a fork for the nanokernel. */ + /** Declares a fork for the nanokernel. */ struct nano_sem *f1; - /*! Declares a second fork for the nanokernel. */ + /** Declares a second fork for the nanokernel. */ struct nano_sem *f2; #else - /*! Declares a fork for the microkernel. */ + /** Declares a fork for the microkernel. */ kmutex_t f1; kmutex_t f2; #endif - /*! Declares the current philosopher's ID. */ + /** Declares the current philosopher's ID. */ static int myId; - /*! Declares an interrupt lock level.*/ + /** Declares an interrupt lock level.*/ int pri = irq_lock(); - /*! Declares the next philosopher's ID. */ + /** Declares the next philosopher's ID. */ int id = myId++; irq_unlock(pri); diff --git a/doc/doxygen/phil_task_commented.c b/doc/doxygen/phil_task_commented.c index a042f1ac1a5..9ff94cfc396 100644 --- a/doc/doxygen/phil_task_commented.c +++ b/doc/doxygen/phil_task_commented.c @@ -1,4 +1,4 @@ -/*! @file +/** @file * @brief An implementation of a solution to the dining philosophers problem * for both the nano- and microkernel. * @@ -67,7 +67,7 @@ struct nano_sem forks[N_PHILOSOPHERS];//!< Declares global semaphore forks for t #ifdef CONFIG_NANOKERNEL -/*! +/** * @brief The nanokernel entry point. * * Actions: @@ -102,7 +102,7 @@ int main (void) #else -/*! +/** * @brief Starts the dining philosophers demo of the microkernel. * * This function starts the dining philosophers demo and