[openbeos] Re: API documentation (part III?)
- From: Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Mon, 05 Mar 2007 18:22:58 +0100
On 2007-03-05 at 14:05:49 [+0100], Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>
wrote:
> "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.
I actually don't know what you're referring to. The Qt API documentation
uses doxygen and I find it pretty OK -- definitely way better than the
BeBook. The only thing I'm missing is a version using frames. Not sure if
doxygen can do that (haven't seen it so far at least). If not, I wouldn't
believe it difficult to create a tool for generating it.
[...]
> > 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.
As long as it doesn't have another syntax I'm happy with using another
tool. I've already written several thousand lines of doxygen comments and
wouldn't like to translate them to another syntax.
CU, Ingo
Other related posts:
