Simple guide to basic Doxygen usage

Make sure to also check out part 2 of this tutorial, “Simple Doxygen templates” for many useful templates and tips.

This is a simple guide to basic use of Doxygen-compliant commenting of source code. The guide is written from my point – C/C++ – but it’s valid for all supported languages, except of Python. See Doxygen documentation for use for Python. Doxygen is very flexible when it comes to the form of how the documentation is written, the layout presented here is simply my preference.

Doxygen is a documentation system for C/C++, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

Installation and setup is very simple for all supported systems, and with Doxywizard, setting up the project of documentation is very simple also.

The harder part is converting the old in-code documentation to Doxygen-compliant one.

Basicly, Doxygen documentation of any “object” (file, function, class, …) consists of brief and detailed description, as follows:

//! Brief description, can span only 1 line
/*!
 * More detailed description.
 * Feel free to span as many lines
 * as you wish... All allowed.
 */

Doxygen supports also in-line comments (comments on the same line as the documented piece of code), both brief and detailed kind; these blocks can only be used to document members and parameters!

void HelpFn1();    //!< Internal.
void HelpFn2();    /*!< Internal. */

Be careful using these though, since it’s easy to make a mistake:

void function1();    //!< Correct
void function2(int i);    //!< WRONG! Comment on parameter i, but function not documented!

//! Some other function.
void function3(int i);    //!< Some int. Correct - both function and parameter documented

Doxygen allows you to document also various aspects of “objects”, for instance:

//! Copy a string.
/*!
 * The strcpy function copies \a strSource, including
 * the terminating null character, to the location
 * specified by \a strDestination. No overflow checking
 * is performed when strings are copied or appended.
 * The behavior of \a strcpy is undefined if the source
 * and destination strings overlap.
 *
 * \param strSource pointer to source null terminated string
 * \param strDestination pointer to destination memory
 * \return \a strcpy returns the destination string.
 * No return value is reserved to indicate an error.
 * \sa wcscpy(), _mbscpy(), strncpy()
 */
char* strcpy(char* strDestination, const char* strSource);

Notice how \a is used to tell doxygen, that strSource and strDestination refer to parameters. The \sa contains the “see also” section of documentation.

Documentation in other places

Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block).
To do so, you need to put a structural command inside the documentation block.

\class to document a C++/Java class
\struct to document a C-struct.
\union to document a union.
\enum to document an enumeration type.
\fn to document a function.
\var to document a variable or typedef or enum value.
\def to document a #define (macros).
\typedef to document a type definition.
\file to document a file.
\namespace to document a namespace.
\package to document a Java package.
\interface to document an IDL interface.

For instance, if you want to document the class Test, put the following documentation block somewhere in the input that is read by doxygen:

/*! \class Test
 * \brief A test class.
 *
 * A more detailed class description.
 */

BEWARE: To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

/*! \file myheader.h
 * \brief A Documented header file.
 *
 * Details about myheader.h.
 */

/*! \def MAX(a,b)
 * \brief A macro that returns the maximum of \a a and \a b.
 *
 * Details.
 */

/*! \var typedef unsigned int UINT32
 * \brief A type definition for unsigned int.
 *
 * Details.
 */

/*! \var int errno
 * \brief Contains the last error code.
 *
 * \warning Not thread safe!
 */

/*! \fn int close(int fd)
 * \brief Closes the file descriptor \a fd.
 * \param fd The descriptor to close.
 */

#define MAX(a,b) (((a) > (b)) ? (a) : (b))
typedef unsigned int UINT32;
int errno;
int close(int);

Part 2 is now out! Check out “Simple Doxygen templates” for templates of sample Doxygen block comments, and many small tips…

14 responses to “Simple guide to basic Doxygen usage

  1. Pingback: Simple guide to Doxygen - Linoleum

  2. Thanks – you’ve just shown me why I couldn’t get my damned enums to show up in the doxygen output (the namespace hadn’t been documented yet). Lifesaver 🙂

  3. I use the rth output.
    I wonder how to control the order that doxygen do the docomentaion.
    I want documents for file main.c will appear before file comunication.c
    Thank in advanced
    David

  4. As far as I know, there is no way to do that other than manual re-arangement after the documentation is generated…
    IMO – Doxygen simply goes through all files in directory and generates documentation; I didn’t find any way to mark a file as “prefered”.

    The only choice of sorting in Doxygen I know of is sorting of detailed and brief descriptions (via SORT_MEMBER_DOCS and SORT_BRIEF_DOCS tags).

    Sorry, and thanks for visit! 🙂

  5. Thank you for helping me improve the documentation for CartoType. Like many people I couldn’t get enums to show up in my main namespace. This is a Doxygen flaw in my opinion: there is no reason why it should not be able to document members of enclosing things like classes and namespaces that are not themselves documented.

  6. Glad I could help! 🙂

    The problem has two sides – it sure is confusing, why the enclosed members cannot appear “by themselves”, but on the other hand, enclosed members without the context of the enclosing class (…) don’t make much sense.

  7. Pingback: » Open source tool for code documentation : Doxygen and Graphviz only god will judge me

  8. How to put the comment inside a function. If I put like that, then this comment is merged with the one, which i commented before the function definition. can u please tell me the soln soon

  9. I ‘ve had some success with documenting our public enums in files other than the header files we give to our customers. This just to keep those public headers “clean”. So for instance I have in public.h:

    enum gType {
    NM_a = 0,
    NM_d = 2
    };

    and then in public.cc I have:
    #include “public.h”

    /*! \enum gType
    \ingroup Public
    Enumerated types for …
    */
    /*! \var NM_a
    \ingroup Public

    */
    /*! \var NM_d
    \ingroup Public

    */

    I include public.cc in my doxygen list of files, and it works. Now instead of a straight enum I have one inside a class – so in publicclass.h:

    class gType {
    public:
    enum Value {
    NM_a = 0,
    NM_d = 2
    };
    };

    I can get the class to document in publicclass.cc, but not the enum. Here’s one example of what I’ve tried in publicclass.cc

    #include “publicclass.h”

    /*! \class gType
    \ingroup Public
    Class holding enum for …
    */
    /*! \enum Value
    \ingroup Public
    Value enumeration type for gType
    */
    /*! \var NM_a
    \ingroup Public

    */
    /*! \var NM_d
    \ingroup Public

    */

    I’ve also tried /*! \enum gType::Value

    Any ideas?
    Heather Myers

  10. Is there any way to be able to change the navigation on the html that is outputted? inside the doxygen wizard. I would prefer not to go in after documentation and change the structure. There is a possibility that for our documentation we will be updating the documentation every 3 months and thats too much editing. Hence why we want automation. Any advice would be great.

  11. So I am having trouble documenting a class as private in a different location:
    /*! \class MyNS.MyClass
    * \internal
    */

    I have my config file set to hide other internal classes, but adding that comment above the class definition does not remove the class from the documentation.

    How do I remove single classes from documentation?

  12. Pingback: Fix Doxygen Show Errors Windows XP, Vista, 7, 8 [Solved]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s