libmad documentation project

I recently started working on a small audio processing project. I chose to use mad library for dealing with mp3 files.

Since I needed to study it for getting enough understanding of it, and the package TODO file calls for contributors to documentation project, I tried to make my notes useful for the programmers community.

One thing I like in java programming is the documentation facility, which generates browseable API documentation directly from comments inserted in source files.

The same functionality is available for C/C++ and other languages, with Doxygen (open-source) program, so I decided to use it.

The resulting documentation

Here's the documentation produced from modified sources. Of course the stylesheets and presentation details may be customized.

In the html system, you can start browsing the files or read High-Level API or Low-Level API and click on symbols from there (links are generated automatically from plain text, in most cases).

Changes to source package

In order to produce useful documentation, Doxygen, like javadoc, expects source comments to be written with a given syntax. Doxygen allows several variants of its syntax, and I chose to use the javadoc-like syntax.

Next is a list of changes I made to source code.

You can download:

• The new source package ( 515K ) .
• The corresponding patch (gzipped unified diff format - 32K )
• The modified (or new) files ( 76K )
• The new html documentation tree (tgz archive - 2,5M )
• The pdf version (1,2M )
• The xml version (tgz archive - 307K )

Adapted source files for auto-generating documentation with doxygen

See Doxygen home page for detailed information

used /** ... */ syntax for concerned comments

Converted them as needed to "use 3rd person (descriptive) not 2nd person (prescriptive)", as recommended in http://java.sun.com/j2se/javadoc/writingdoccomments/ .

The auto-brief option is used, so I added dots in some places to delimit "brief description".

converted the "NAME: .* \n DESCRIPTION: .*" formatted comments

original contents saved as doc/oo.xml so it's easy to reconvert if needed.

created doxygen-specific documentation files:

libmad.dox

is used as main page and contains essentially the README file information.

highlevel.dox and lowlevel.dox

Are linked to main page and describe the high-level and low-level API usage.

Their contents is picked up from mad-dev mailing list archives: message #369 from Joe Drew and message #373 from Rob Leslie

config.dox

Created from config.h, it documents the autotools configuration options.

replaced auto-generated "mad.h" with one including the others.

This allows doxygen to detect actual dependencies.

Defined typedefs for callback functions

in "callbacks.h", used them in decoder.[hc]

Then high-level definitions may be better documented, and cross-references reported.

NOTE: these changes do not involve real changes in compiled library. The generated documentation is thus compatible with version 0.15.1b. However, developers may need to download "callbacks.h" to use the new typedefs.

TODO

The changes I made involve a little more work :

remove mad.h target in makefile

Its documentation role would be replaced by the new generated documentation.

update version information as needed (configure.ac changed)

Your comments are welcome