docs/user/HOWTO

   1
   2 THE HAIKU BOOK HOWTO
   3
   4 The end user documentation for Haiku is automatically generated from the
   5 source code using the Doxygen tool. We are talking BeBook-style documentation
   6 here, not development related docs (those belong in trunk/docs/develop).
   7
   8 This HOWTO only explains how to include your kit into the "Haiku Book", it
   9 is not a Doxygen tutorial. For information about using Doxygen, see the Doxygen
  10 manual, www.doxygen.org, and OpenBeOS newletters 31 and 29.
  11
  12 There are two ways to document your kit:
  13
  14         1)      Put the Doxygen comments in your headers and/or source files.
  15         2)      Put the Doxygen comments in separate files.
  16
  17 Either way is fine. The documentation for the Midi Kit, for example, uses the
  18 latter option. The files with the Doxygen comments all live in the midi2 subdir
  19 of trunk/docs/user. Of course, if you embed the Doxygen comments directly in
  20 your source code, you don't need to make a subdir in trunk/docs/user.
  21
  22 There is one Doxygen config file (Doxyfile) for the entire book, so you don't
  23 have to make your own Doxyfile. You just have to add the directories with your
  24 commented files to the INPUT directive, so doxygen will know where to find them.
  25 You probably also want to add a link to your kit on the main page (book.dox).
  26
  27 To generate the docs, simply type "doxygen" in the Terminal. The script puts
  28 the resulting HTML docs in "trunk/generated/doxygen/html".
  29
  30 Note: theoretically, Doxygen allows us to treat each kit as a separate "module",
  31 using the \defgroup and \ingroup tags. In practice, the results of this are a
  32 little disappointing. That's why, at least for the time being, we simply lump
  33 everything together, and give each kit one or more \page's. Feel free to take a
  34 peek at the Midi Kit docs to figure out what the hell that means ;-)