Commit 54be4ec0 authored by PRUVOST Florent's avatar PRUVOST Florent
Browse files

add a first documentation for code commenting with doxygen

parent be88374a
#+TITLE: Doxygen Documentation
Document all functions prototypes, modules, macros, structures and
variables. Doxygen is not very flexible: read this documentation and
follow the guidelines. Remember to generate the documentation, and
check that it appears as expected.
The file ~xxxx.c~ has examples of all features used in the
documentation.
* Functions Prototype Documentation
To document a function, use the following format:
#+begin_src c
/**
*******************************************************************************
*
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the function
*
* Multiple lines explaining the detailed function behavior
* exceptions, preconditions, algorithm, etc.
*
*******************************************************************************
*
* @param[inout] name_of_parameter
* Explanation of the parameter
*
* @param[in] name_of_parameter
* Explanation of the parameter
*
*******************************************************************************
*
* @return Explain what is returned by the function
*
* or
*
* @retval value1 explanation of the returned value and in which case it is returned
* @retval value2 ...
*
*******************************************************************************/
int
function(int param1, int *param2)
{
}
#+end_src
~[in]~ *must* be attached to ~@param~, and *it must* be /lower
case/. Otherwise, Doxygen thinks the name of the parameter is ~[IN]~.
Blank lines are /important/: there must be a blank line between ~@brief~
and the ~details~ section.
* Structures documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
* @brief Single line explanation of the structure
*
* General description of the structure
*/
struct name_s {
type1 field1; /**< What is stored in this field */
type2 field2; /**< What is stored in this field */
};
#+end_src
It is important to use the ~/**<~ marker, or the description of the
field is not imported in an array representation of the data
structure.
* Macros Documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the macro
*
* General description of the macro if needed
*/
#define macro
#+end_src
Without the ~@brief~, the documentation does not appear just under the
macro definition. All macro definitions are output directly in the
generated documentation.
* Variable Documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the variable
*
* General description of the variable if needed
*/
int var;
#+end_src
Without the ~@brief~, the documentation does not appear just under the
variable definition.
* Modules Documentation
General documentation on how the functions of a same module are used
together belong to the Module documentation section. Modules are
defined with the following format in the groups.dox file:
#+begin_src c
/**
* @defgroup name_of_module Readable Name Of Module
* @ingroup name_of_parent_module
* @{
*
* @brief One line description of module
*
* Multiple lines description of module
* Can use markdown language features, like
* sharp for section headers, etc.
*/
...
/** @} */
#+end_src
All functions between ~@{~ and ~@}~ belong to the same Module. Most
modules have already been created, look for defgroup. Some of them
are defined in the file ~groups.dox~, because they span over multiple
files in the source code.
* DOs and DO NOTs
** Functions Prototypes
*DO* comment all functions at their function definition (typically .c
file), or, if they are static functions used in a single file,
before the function definition.
*DO NOT* comment /both/ the function definition and the function
prototype, or the documentation of the function will be duplicated.
** Doxygen Comments
All ~/** ... */~ comments are interpreted by Doxygen as to be added
to the documentation.
If you enter a ~/** ... */~ comment without Doxygen commands in it,
all the text of the comment will be appended to the next Doxygen
group.
So, *DO NOT* start comments inside the code with ~/**~, despite the
nice coloring of your editor. All these comments make no sense once
they are appended to the next function or structure documentation.
*DO* configure your editor to use your preferred coloring scheme for
normal comments :)
** Doxygen keywords
Any ~@something~ inside a ~/** ... */~ block is interpreted as a
Doxygen keyword. Doxygen stops parsing the entire file if it finds
a keyword it does not know. *DO NOT* use your own keywords, *DO* check
the generated documentation.
* Modules Structure
All functions, macros, variables should belong to a module. *DO* look
at the documentation to see the structure, and if you document a
function, be sure that it belongs to the right module. *DO NOT* just
document a function without enclosing it inside a ~@addtogroup @
... @}~ group, or without adding a ~@ingroup group_name~ before the
function definition.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment