#+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.
