Development/Doxygen

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

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 /**< or ///< (i.e. < 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

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.

 Usage example:
 @code
 SwCrsrSaveState save( cursor );
 // do work
 if( restore )
     cursor.RestoreSavePos();
 @endcode

 @see SwCursor::RestoreSavePos()
 @since LibreOffice 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).

Building

If you want to preview the API documentation locally, pass --enable-odk to autogen.sh and do not pass --without-doxygen.
Then either run make or solely make odk and open the file workdir/CustomTarget/odk/docs/idl/ref/index.html with a browser.