Editing Doxygen (section)

== Example ==

All examples are given for languages with C-like comments where a multi-line comment starts with <code>/*</code> and a single line comment starts with <code>//</code>.

Doxygen ignores a comment unless it is marked specially. For a multi-line comment, the comment must start with <code>/**</code> or <code>/*!</code>. A markup tag is prefixed with a [[backslash]] (<code>\</code>) or an at-sign (<code>@</code>).<ref>[https://www.doxygen.nl/manual/commands.html Doxygen: Special Commands]</ref> The following is a relatively simple function comment block with markup in bold:

 /*'''*'''
 ''Function description''
 '''@param''' ''p1 Parameter description''
 '''@param''' ''p2 Parameter description''
 '''@return''' ''Return description''
 */
 void foo(int p1, int p2) {}

A block can be formatted various ways. A common way is to left-align 
asterisks on each line which Doxygen does not include in the output. For example:

 /*'''*'''
  * ''Function description''
  * '''@param''' ''p1 Parameter description''
  * '''@param''' ''p2 Parameter description''
  * '''@return''' ''Return description''
  */
 void foo(int p1, int p2) {}

Alternatively, a block can consist of a series of single-line comments. Doxygen accepts comments with an additional slash (<code>/</code>) or exclamation (<code>!</code>).<ref>[https://www.doxygen.nl/manual/docblocks.html#cppblock Doxygen: Documenting the code - §Comment blocks for C-like languages]</ref>

 //'''/''' ''Function description''
 //'''/''' '''@param''' ''p1 Parameter description''
 //'''/''' '''@param''' ''p2 Parameter description''
 //'''/''' '''@return''' ''Return description''
 void foo(int p1, int p2) {}

To locate a documentation comment to the right of the code, an additional <code>&lt;</code> marker is required.<ref>[https://www.doxygen.nl/manual/docblocks.html#memberdoc Doxygen: Documenting the code - §Putting documentation after members]</ref> This allows for an alternative approach for documenting parameters as shown below.

 /*'''*'''
  * ''Function description''
  */
 void foo(int p1 /**<Parameter description*/, int p2 /**<Parameter description*/) {}

A mathematic formula can be specified via [[LaTeX]] commands. For example:

<syntaxhighlight lang="cpp">
/**
 * An inline equation @f$ e^{\pi i}+1 = 0 @f$
 * A displayed equation: @f[ e^{\pi i}+1 = 0 @f]
 */
</syntaxhighlight>

A more complete example in C++:

<!--
Please regenerate the screenshot image with the latest source code.
[[Image:Doxygen ouput.png|thumb|A screenshot of what the output would look like in HTML]]

There is no guarantee the size of int or long in C/C++ is enough to represent Unix time in milliseconds.
Do not use int or long for time representation. long long or int64_t must be used instead.
-->
<syntaxhighlight lang="cpp">
/**
 * @file
 * @brief Time class header
 * @author John Doe <jdoe@example.com>
 * @version 1.0
 * @copyright CC BY-SA or GFDL
 * @sa <a href="https://en.wikipedia.org/wiki/Wikipedia:Copyrights">Wikipedia:Copyrights - Wikipedia</a>
 */

/**
 * Represents a moment of time
 * @author John Doe
 */
class Time {
public:
    /**
     * Construct with a duration since Jan 1, 1970
     * @param millis A number of milliseconds
     */
    explicit Time(long long millis) : m_millis(millis) {
    }

    /**
     * Get a new instance with the current time
     * @return Instance
     */
    static Time now() {
        // ...
    }

private:
    long long m_millis; ///< Milliseconds since Jan 1, 1970
};
</syntaxhighlight>