[openbeos] Re: API documentation (part III?)
- From: "Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Fri, 09 Mar 2007 17:49:27 +0100 CET
Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx> wrote:
> On 2007-03-05 at 14:05:49 [+0100], Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>
> > wrote:
> > 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 BeBook is indeed hard to use without BeHappy. That's one thing I
like about JavaDoc, even though I prefer BeHappy for its method
overview when you're "inside" a class. Anyway, the Qt *contents* are
fine, just the presentation looks horrible IMO. And the way Doxygen's
output is done, it's not as customizable as it could be. They more or
less prevent the fancy stuff you could do with CSS.
JavaDoc has even customizable output via Doclets - while that's more
than what most people need, Doxygen's output is of poor quality.
> 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.
Probably not.
> [...]
> > > 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.
Definitely, the current syntax should be kept.
Bye,
Axel.
Other related posts:
