This page is for notes on using Doxygen to document the Kodi's Add-On headers source code.

Doxygen, is a documentation system for C++, C, Java, and some other weird languages. It can generate html docs documenting a projects source code, by either extracting special tags from the source code (put there by people wanting to make use of doxygen), or doxygen attempts to build documentation from existing source.

Doxygen seems to be installed on the NMR systems, type:

doxygen --version

Start doxygen documentation for add-ons always with /// and on Kodi itself with /*!, this makes it more easy to see for which place the documentation is.

Here an example on add-on about function coding style:

#ifdef DOXYGEN_SHOULD_USE_THIS
  ///
  /// \ingroup python_xbmcgui_window
  /// @brief Sets the resolution
  ///
  /// That the coordinates of all controls are defined in.  Allows Kodi
  /// to scale control positions and width/heights to whatever resolution
  /// Kodi is currently using.
  ///
  /// @param[in] res                Coordinate resolution to set
  ///  Resolution is one of the following:
  ///  | value | Resolution                |
  ///  |:-----:|:--------------------------|
  ///  |   0   | 1080i      (1920x1080)
  ///  |   1   | 720p       (1280x720)
  ///  |   2   | 480p 4:3   (720x480)
  ///  |   3   | 480p 16:9  (720x480)
  ///  |   4   | NTSC 4:3   (720x480)
  ///  |   5   | NTSC 16:9  (720x480)
  ///  |   6   | PAL 4:3    (720x576)
  ///  |   7   | PAL 16:9   (720x576)
  ///  |   8   | PAL60 4:3  (720x480)
  ///  |   9   | PAL60 16:9 (720x480)
  /// @return                       Nothing only added as example here :)
  /// @param[out] nothingExample    Example here, if on value pointer data becomes
  ///                               returned.
  /// @throws TypeError             If supplied argument is not of List type, or a
  ///                               control is not of Control type
  /// @throws ReferenceError        If control is already used in another window
  /// @throws RuntimeError          Should not happen :-)
  ///
  ///
  ///--------------------------------------------------------------------------
  ///
  /// **Example:**
  /// ~~~~~~~~~~~~~{.py}
  /// ..
  /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
  /// win.setCoordinateResolution(0)
  /// ..
  /// ~~~~~~~~~~~~~
  ///
  setCoordinateResolution(...);
#else
  SWIGHIDDENVIRTUAL bool setCoordinateResolution(long res, int &nothingExample);
#endif

```
/// \ingroup
```
- Define the group where the documentation part comes in.
```
/// @brief
```
- Add a small text of part there.
```
/// TEXT_FIELD
```
- Add a bigger text there if needed.
```
/// @param[in] VALUE_NAME                 VALUE_TEXT
```
- To set input parameter defined by name and add a description. There the example also add a small table which is useful to describe values.
```
/// @param[out] VALUE_NAME                VALUE_TEXT
```
- To set output parameter defined by name and add a description.

/// @return                               VALUE_TEXT

- To add a description of return value.

```
/// @throws ERROR_TYPE                    ERROR_TEXT
```
- If also exception becomes handled, can you use this for description.
```
/// TEXT_FIELD
```
- Add a much bigger text there if needed.
```
/// ------------------
```
- Use this to define a field line, e.g. if you add example add this always before, further must you make two empty lines before to prevent add of them on string before!
```
/// ~~~~~~~~~~~~~ 
```
- Here can you define a code example which must start and end with the definition string, also can you define the code style with e.g. {.py} for Python or {.cpp} for CPP code on the first line of them.

Note: Start all VALUE_TEXT at same character to hold a clean code on *.cpp or *.h files.

The #ifdef DOXYGEN_SHOULD_USE_THIS on example above can be becomes used if for Doxygen another function is needed to describe.

If you want to prevent a part from doxygen can you define #ifndef DOXYGEN_SHOULD_SKIP_THIS or #ifdef DOXYGEN_SHOULD_USE_THIS on the related code.