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

"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
> There are pros and cons. Many of the people here have 'grown up' with
> the Be Book and that's probably why there is a hang towards the
> original structuring. However, many of the audience we might reach
> have not. And don't forget that we have a lot of power over the 
> output
> - either by CSS and HTML headers, or crudely by hacking into doxygen.

It's not a matter of being grown up with the BeBook - because I didn't; 
I just dislike the doxygen style documentation a lot. I consider 
doxygen to be an inferior tool for its job.
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.

> The current doxygen XML output is considered to be bad, but I saw on
> their mailing list that a newer XML structure is in the works. If I
> would develop doxygen, I would consider moving over everything to 
> XML,
> and indeed use XSLT to transform the data to other formats. It would
> make doxygen a bit less hackish (to me).

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

> Just to be clear on the XML position. I sort of agree with Ingo that
> humans are not made to read and write XML. I have been cheating
> somewhat, as I'm using an XML editor, so I don't make any mistakes
> with regard to the syntax and the structure (which Docbook imposes). 
> I
> also don't want to denounce using Docbook altogether. The UI
> guidelines are the perfect example of something that should have been
> (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.

> 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.

> 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.
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.
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.
After all, we still have plenty of time until R1.

Bye,
   Axel.

Other related posts: