54ffe82333
Edited defines.rst file for coherence and usability. Change-Id: If572eb9daa31d0bd9ef7cb1f22e6dca3ff8c578f Signed-off-by: Gerardo Aceves <gerardo.aceves@intel.com>
74 lines
No EOL
1.8 KiB
ReStructuredText
74 lines
No EOL
1.8 KiB
ReStructuredText
.. _defines:
|
|
|
|
Define Documentation
|
|
####################
|
|
|
|
Defines and functions are documented similarly. Some noteworthy
|
|
differences are:
|
|
|
|
* The best practice for defines requires the use of the **@def**
|
|
special command.
|
|
|
|
* Just as with functions, we provide a full and a simplified template.
|
|
The syntax used in the simplified template should only be used if you are familiar with
|
|
Doxygen. Use the full template if you are having problems
|
|
generating the documentation properly.
|
|
|
|
Define Comment Templates
|
|
************************
|
|
|
|
Full template:
|
|
|
|
.. code-block:: c
|
|
|
|
/** @def name_of_define
|
|
*
|
|
* @brief Brief description of the define.
|
|
*
|
|
* @details Multiple lines describing in detail the
|
|
* purpose of the define and what it does.
|
|
*/
|
|
|
|
#define name_of_define
|
|
|
|
Simplified template:
|
|
|
|
.. code-block:: c
|
|
|
|
/**
|
|
* Brief description of the define.
|
|
*
|
|
* Multiple lines describing in detail the
|
|
* purpose of the define and what it does.
|
|
*/
|
|
#define name_of_define
|
|
|
|
Define Documentation Example
|
|
****************************
|
|
|
|
This simple example shows how to document a define with the least amount
|
|
of effort while still following best practices.
|
|
|
|
Correct:
|
|
|
|
.. literalinclude:: phil_commented.h
|
|
:language: c
|
|
:lines: 32-47
|
|
:emphasize-lines: 2, 3, 5
|
|
:linenos:
|
|
|
|
Observe how each piece of information is clearly marked. The @def on line 2
|
|
ensures that the comment is appropriately linked to the code.
|
|
|
|
Incorrect:
|
|
|
|
.. literalinclude:: ../../../../samples/philosophers/microkernel/src/phil.h
|
|
:language: c
|
|
:lines: 25-34
|
|
:emphasize-lines: 2, 5
|
|
:linenos:
|
|
|
|
Observe that the comment does not start with
|
|
:literal:`/**` and therefore Doxygen will ignore it.
|
|
|
|
The comment is ambiguous; it could apply to either the define or the #if. |