User:Llunak/Doxygen

Writting 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 writting 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 writting 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

Example of a documented class
/** A helper class to save cursor state (position). Create SwCrsrSaveState object to save current state, use SwCursor::RestoreSavePos to actually restore cursor state to the saved state. It is possible to stack several SwCrsrSaveState objects.

@see SwCursor::RestoreSavePos @since 4.3.0 class SwCrsrSaveState { public: /**    * Saves the state of the given SwCursor object. * @param rC cursor object to operate on    */ SwCrsrSaveState( SwCursor& rC ); /**     Note: The destructor only discards the saved value. Use SwCursor::RestoreSavePos to restore the SwCursor object passed to the constructor to the saved state. */   ~SwCrsrSaveState; /// A completely unused enum enum Foo {       FooFirst, ///< first value of the unused enum FooSecond /**< second value of the unused enum */ };   /**     An unused function This function does not do anything useful. @return the value 42 */   static int lifeUniverseAndEverything; private: SwCursor& rCrsr; };

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).