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

["Brian Verre" <bverre@xxxxxxxxxxxxxx>]

I'd like to offer Niels a little feedback from someone not in any type of Haiku 
decision hierarchy...
 
Your points were well reasoned, and were stated clearly. User-friendliness, 
simplicity, automation, not re-inventing the wheel, etc. Hit home with me.
 
It would be my opinion that any project with a scope as broad as Haiku needs a 
'living document'; specifications and examples that can be updated in a 
flexible, wiki type of way. Perhaps when stable release stages are reached, 
printed or locked editions might be more desirable. I would be surprised if the 
Doxygen user base haven't worked out sufficient methods of converting Doxygen 
output to various print/typeset formats or PDF.
 
While I have not used either documentation utility, I have seen Doxygen 
utilized extensively throughout the years and it would seem to a layman like me 
that it is a very well supported project itself.
 
Anyways, I hope you receive feedback as well thought out as what you put on the 
table. I'm merely commenting because I think working with the technical 
documentation may be one of the areas I could be most helpful to the Haiku 
project. 
 
At work I often have to extend a medical MIS with workarounds, external 
utilities, and hand crafted scripts and even executables, so while familiar 
with re-inventing the wheel (in comparison with superior systems) I would dread 
having to constantly work with a clunky system in a hobby project that I look 
to for fun, continuing education, and is generally a great idea (with friendly 
folks standing behind it).
 
Regards,
Brian

________________________________

From: openbeos-bounce@xxxxxxxxxxxxx on behalf of Niels Reedijk
Sent: Fri 3/2/2007 10:38 AM
To: Haiku Mailinglist
Subject: [openbeos] API documentation (part III?)



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.