FreeLists / openbeos / [openbeos] API documentation (part III?)

["Niels Reedijk" <niels.reedijk@xxxxxxxxx>]

Hi guys,

I'm explicitly directing this mail to people who have expressed
opinions on API documentation before. I am very interested in your
reactions Axel, Jerome, Stephan, Miguel, and everyone I can't directly
find in my quick gmail search.

With revision 20307 I introduced documentation for more classes of the
support kit. I have been playing around with documenting for a few
months, both in Docbook and Doxygen documentation. For some reason it
was understood that 'people' had decided on using docbook. Jerome
Duval and I both have been playing around with it (note, this mail
does not necessarily reflect his opinion - I'm mentioning him for
historical acuracy). I'm interested in investing more time in writing
and checking documentation, and I'm interested to co-ordinate with
developers on writing API documentation, however, there need to be
made some decisions first.

The choice is between using Doxygen or Docbook as a source format for
the Haiku Book.

I have made it no secret in the past that I actually dread Docbook,
but I do recognise that it is a major format in the documentation
sector and I also understand why. That's why I have been playing
around with it. And to cut it right to the chase, I'm against it now
as well. It's bloated, it's inconvenient to say the least and, most
importantly, _it's not made for the job_. Using Docbook effectively
would mean writing a header parser that generates docbook to match the
method prototypes, manually structuring things to the proper level
(sect1, sect2, sect3), working out some magic for interesting cases.
Hey... that's stuff doxygen does for free!

Seriously though, Doxygen parses the header files and structures
things for free. Furthermore, it creates a wonderful HTML output that
I argue is probably better than the format of the BeBook. Think about
it, Doxygen has somewhat become a standard in the open source world,
many developers (OS enthousiasts) we are trying to reach know it and
will instantly be able to work with the haiku book. And very important
is that it _works today_, without having written a single line of a
header parser.

So what will we be losing? Well, some output formats. Docbook is
capable to being transformed into PDF. Doxygen is as well, but with a
detour and it probably won't turn out to be very good because of some
of the tricks I use. I haven't tried it though. Is this a bad thing?
In my opinion it isn't. I doubt anyone is going to print out the whole
thing and use it instead of the conveniently hyperlinked and up to
date online version. Seriously, if we ever need to have a good PDF for
whatever reason, we'll work it out when the time comes.

We'll also be losing some flexibility in structuring, because doxygen
is based on certain assumptions. Have I encountered them yet? Yes, I
have encountered a small thing that I'm not very happy about, but I
have worked around it. And remember, doxygen is open source, so the
small inconveniences could even be fixed in the program itself.

At this point I will say without a doubt that Doxygen is the best
choice based on our resources, our goals and our data. Doxygen both as
a tool and as a format is perfectly capable of creating a
well-structured API book. It's major advantage over docbook is that
any fool can learn the basics in a fraction of the time it takes to
even write some basic docbook. And as an additional bonus, I like it
and I'm interested on working on the Haiku book.

The goal of this mail is to get some support. I would hate it for my
work to be completely lost because someone in a higher location in the
hierchy tosses my work away because it doesn't conform to an ideology.

Niels.