C docs: help Doxygen recognize class structure

Question

I have a C library for which I would like to auto-generate some API documentation. Doxygen seems to be the de facto tool for this type of thing, so I've written a couple toy classes (using the same coding style as my library) to test it out. A couple of notes about the coding style:

• Each class has a header (.h) file containing a typedef of the class's data structure and prototypes for all class methods. This is the information I want users of my library to be able to see.
• A corresponding .c file contains the full data structure definition as well as the implementation of all the class methods. The details of implementation should not show up in the API docs.
• See https://github.com/standage/doc-test for the toy example code.

When I run Doyxgen on my example, this is what I get: http://standage.github.io/doc-test. The resulting docs are a bit kludgy--there is a list of data structures and a list of files. Ideally, what I would like is a class list, where each class page shows the functions/methods associated with that class, and where class names link to the detail page for that class. Is this possible with Doxygen (or any other tool)?

Answer 1

Doxygen supports documentation of "C classes" - just add

1. the \class directive to the struct containing its data members
2. the \memberof directive to its functions
3. \public or \private directive to functions/members

Example:

/** This is My Class!
    \class MyClass
    */
typedef struct MyClass
{
 /** This is member A 
   \private
   */
 int memberA;
 /** This is member B 
   \private
   */
 int memberB;

} MyClass;

/** A private member function of MyClass
    \param i Some value
    \private
    \memberof MyClass
    */
static void MyClass_privateFunction(struct MyClass* this, int i)
{
}

/** A public member function of MyClass
    \param j Some other value
    \public
    \memberof MyClass
    */
void MyClass_publicFunction(struct MyClass* this, int j)
{
}

If you set Doxygen's EXTRACT_PRIVATE to NO, only the public part will be documented.

Answer 2

Take a look at the Exclude series of tags in your configuration file.

Since your source is in the ./src/ directory, one option might be to use one of the following:

Exclude a directory:

EXCLUDE = /src

Exclude a pattern of file names:

EXCLUDE_PATTERNS = *.c

These are off of the top of my head. You might have to add some path information. I expect that using the first or both will produce output that does not have any of the comments in your C files.

As a side note, do you think using a structure for the interface for your 'class' would meet your requirements?