35 lines
1.8 KiB
Plaintext
35 lines
1.8 KiB
Plaintext
|
|
||
|
|
THE OPENBEOS BOOK HOWTO
|
||
|
|
|
||
|
|
The end user documentation for OpenBeOS 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 "OpenBeOS 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 ;-)
|