Development/Doxygen

Writing API documentation using Doxygen
All API (Application Programming Interface) should be documented. LibreOffice uses Doxygen for API documentation, which uses specially marked comments written directly in the source code and generates fulltext documentation from them.

This page explains basics of writing API documentation using Doxygen and should be sufficient for normal usage in LibreOffice. If you need to know more details, read Doxygen documentation.

Documentation format
Classes, function, types and other API components are documented by writing specially marked comments next to them. These comments start with /** for multi-line documentation (i.e. one extra *) and /// for one-line documentation (i.e. one extra /) and are placed directly before the object they document. If they are to be placed after the object (such as when documenting enum members), they start with /**&lt; or ///&lt; (i.e. &lt; appended).

Each documentation comment typically starts with one line that gives a brief description of the object in one sentence, followed by an empty line and a full multi-line description, and ends with a list of special tags that start with @.

The most commonly used tags are:
 * @see - adds a reference to the given object (related classes, functions, types etc. should be mentioned here if not obvious)
 * @since - marks the first version in which the object has appeared
 * @param - a one-line description of the given argument of the function
 * @return - a one-line description of the return value of the function
 * @code - paired with @endcode, text between these tags is treated as C++ code

Tips

 * The documentation is written in the source code (header files usually) and so it can be also easily read there.
 * Try to document anything non-trivial (special requirements for the call, side-effects, etc.)
 * Avoid documenting what is trivial (for example, stating in the documentation that a constructor is a constructor is pointless).

Building
If you want to preview the API documentation locally, build the documentation with, then open the file   with a browser.