documentation generation

From: Daniel Black <daniel.subs_at_internode.on.net>
Date: Sat, 24 Oct 2009 22:54:44 +1100

I know that documentation is fun and exciting but it seems we're getting too
much fun by doing documentation in the source code as well hand making html
files.

To assist in this fun reduction I did some investigation into Doxygen comment
to html documentation generation.

For a view its probably easiest to download:

http://gitorious.org/opendkim/libopendkim/archive-tarball/doxygen

and look in the doctest/html directory.

How easy was it?

BASIC SETUP:

doxygen -g to generate Doxygen config file:
Setting the project name, the source file - only dkim.h, and documentation
output directory.
To account for the __P macros the following change was needed.

http://gitorious.org/opendkim/libopendkim/commit/1656ab1549535ad1421e834dcdd1c7d1f88f0f5a

run doxygen.

because all the global functions were a little buried doxygen -l generated a
xml guide that I edited to move globals to the top level.

FUNCTIONS:

To get functions documented here's the diff on dkim_sign.

http://gitorious.org/opendkim/libopendkim/commit/e9561f9bd637393d8dab9d3cee021ba15dafed1d

basicly javadoc rules apply. '/**' to start a doxygen comment. option _at_param
and _at_return to describe parameters and any other documentation you want.

ENUMS:

I've found it documents and links enums better than it does #defines so as an
example:

http://gitorious.org/opendkim/libopendkim/commit/4791abecb11bde0fc6db976bc5522bbdc10c0f4f

shows the DKIM_STATS enum.

Aside - is there are reason for using #defines over enums? I would of though
enums are a little more typesafe and intuitive with compiler errors.

DEFINE GROUPS:

Having said that groupings like of #defines DKIM_CBSTAT can still be done
http://gitorious.org/opendkim/libopendkim/commit/9618c17b0989ff9b8ad2717e5d787b09de43b407

(#defines can't have comments at the end of them)

CONCLUSION:

its pretty easy. will require a bit of checking get the best out of current
html doco and the source code. Small autoconf/automake changes will account
for this. doxygen won't be needed on the user's machine.

Interested?
Received on Sat Oct 24 2009 - 11:55:05 PST