haiku/docs/user/HOWTO

THE HAIKU BOOK HOWTO

The end user documentation for Haiku is automatically generated from the 
source code using the Doxygen tool. We are talking BeBook-style documentation 
here, not development related docs (those belong in /current/docs/develop).

This HOWTO only explains how to include your kit into the "Haiku Book", it
is not a Doxygen tutorial. For information about using Doxygen, see the Doxygen
manual, www.doxygen.org, and OpenBeOS newletters 31 and 29.

There are two ways to document your kit:

	1)	Put the Doxygen comments in your headers and/or source files.
	2)	Put the Doxygen comments in separate files.

Either way is fine. The documentation for the Midi Kit, for example, uses the
latter option. The files with the Doxygen comments all live in the midi2 subdir
of /current/docs/user. Of course, if you embed the Doxygen comments directly in
your source code, you don't need to make a subdir in /current/docs/user.

There is one Doxygen config file (Doxyfile) for the entire book, so you don't
have to make your own Doxyfile. You just have to add the directories with your
commented files to the INPUT directive, so doxygen will know where to find them.
You probably also want to add a link to your kit on the main page (book.dox).

To generate the docs, simply type "doxygen" in the Terminal. The script puts 
the resulting HTML docs in "/current/distro/x86.R1/beos/docs".

Note: theoretically, Doxygen allows us to treat each kit as a separate "module", 
using the \defgroup and \ingroup tags. In practice, the results of this are a 
little disappointing. That's why, at least for the time being, we simply lump
everything together, and give each kit one or more \page's. Feel free to take a
peek at the Midi Kit docs to figure out what the hell that means ;-)