Documenting object-oriented C code with Doxygen

From juliano.info

Jump to: navigation, search

Doxygen 1.5.7, released Sep 28, 2008, implements a new useful feature of particular interest for people doing object-oriented programming in C or other languages that don't have native representation of such concept.

Object-oriented programming in C is not uncommon. It is usually done by promoting struct constructs to classes, and specific functions to methods. There are many different (but similar) ways to achieve this. Google provides plenty of links about object-oriented programming in C.

There are libraries like GLib/GObject that provides this sort of functionality for your project. It is, indeed, the base of the GNOME desktop environment, which is written mostly in C.

Projects based on the GLib, GTK+ and GNOME libraries had to rely on gtk-doc in order to properly document their OOP constructs. Although gtk-doc has a few nice features, like automatically detecting inheritance and member function association through GObject introspection, having a second options is always a good idea. Also, gtk-doc won't help if you implement a simpler OO mechanism (i.e., not using GObject).

Now, Doxygen has three new commands that allows the annotation of OO inheritance and memberships directly in the documentation of C code:

\extends base-class
Creates an inheritance relation of the current structure as derived from the given one.
\implements base-interface
Creates an implementation relation of the current structure to the given one (internally, it behaves exactly like \extends, the different name aids the reading of the documentation in the source code).
\memberof class
Makes the current function a member of the given class.

Also, the existing commands \private, \protected and \public had their purpose expanded, and can be used together with these new commands.

Some example code that uses these new features:

typedef struct Object Object;   //!< Object type
typedef struct Vehicle Vehicle; //!< Vehicle type
 
/*!
 * Base object class.
 */
struct Object
{
  int ref;    //!< \private Reference count.
};
 
/*!
 * Increments object reference count by one.
 * \public \memberof Object
 */
Object * objRef(Object *obj);
 
/*!
 * Vehicle class.
 * '''\extends Object'''
 */
struct Vehicle
{
  Object base;    //!< \protected Base class.
};
Views