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

  • From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
  • To: openbeos@xxxxxxxxxxxxx
  • Date: Mon, 5 Mar 2007 18:25:57 +0100

2007/3/5, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
If you want to see how Doxygen should work, have a look at Javadoc;
even the default output is much better than anything you can produce
with doxygen. I don't think Javadoc is perfect, either, but at least
the output is what I would expect from such a tool.

(and)

Definitely, the current output (be it HTML or XML) is just bad and not
really made for use with either CSS or XSLT.

So you're generally unhappy with the output of Doxygen. Read on :-)

> (and is) written in docbook. It's just that this documentation
> doesn't
> require to stay in sync with headers and has links all over the
> place.

FWIW I agree as well, I just had the impression you actually wanted to
code some tools that would automate the task.

Yes, but then I realised that this would mean a lot of magic and
reinventing the wheel. Why would I want to write or adapt a header
parser and an entity generator when Doxygen takes care of that for me.
Read on for a thorough conclusion though :-)

> The user documentation team will need to have a good discussion on
> this issue. I have some thoughts, but it belongs in another thread.

I wouldn't even mind if the user documentation would be written in a
Wiki, and exported to PDF and HTML from there. Even though Docbook
sounds like a good idea there as well.

To be honest, I think docbook would be the way to go with user
documentation. But please, if the will exists to start on user
documentation, let's discuss that in a separate thread.

> So how to proceed?

Since I would still like to have the possibility to generate Docbook, I
think we should aim to be able to produce good XML output out of our
documentation sources.

Agreed. Good XML output gives enough flexibility for the future.

Since doxygen is, in many regards, an inferior tool to create
documentation, I wouldn't like to use it, though. However, there are
many alternatives to doxygen, and its syntax seems to be very similar
to other options, if not compatible already.
Therefore, as long as we don't actually use doxygen to produce our
final docs, I'd be okay with using its syntax for now.

So just to make clear. We can divide doxygen up into three parts.
First, there's the header parser that does it's job just fine.
Secondly, there's the markup language it defines and thirdly there's
the output. At this point we can conclude that at least the first two
components are doing its job, whereas with a docbook implementation we
wouldn't have the first component, and the second component, the
markup language, is horrifying, and the output component needs
tweaking.

IMO we should just check the existing alternatives one by one, and see
if one does the job in a better way, and eventually is less file
centered and allows for more and better grouping. If we don't find a
viable alternative, there is still the option of extending an existing
tool to do what we want.

I think this would be one of the objectives of the API documentation
teamlet. Look around to see what the options are with regards to the
output format. In the meantime, doing one thing doesn't exclude us
from doing the other part, documenting. If we just decide to stay with
the Doxygen style.

After all, we still have plenty of time until R1.

That's true, but it is continually getting nearer, and I think we do
want a Haiku Book before R1.

Niels

Other related posts: