[openbeos] Re: The Haiku Book
- From: "Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Mon, 11 Sep 2006 15:10:35 +0200 CEST
"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
> 2006/9/11, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
> > Stephan Assmus <superstippi@xxxxxx> wrote:
> > IIRC beyond the reasoning of using DocBook because of its many
> > output
> > formats, we didn't like using doxygen for end user documentation
> > simply
> > because it would blow up the source files that much.
> That blowing up is relative. Yes, there are probably sections that
> require a lot of documentation, such as overview pages and class
> descriptions, but most methods will have a simple documentation. And
> there's always the possibility of separating the documentation into a
> special file, as done with the midi2 kit.
Can doxygen parse the sources and compare that to external sources/
headers?
If not, there is little value in using it IMO.
> I'll also question your idea of 'clutter'. Yes, there is data in
> those
> files that aren't used for any practical purpose in compiling or
> developing the code. At the other hand, it doesn't influence you very
> much either. All the editors mark comments in a different way than
> code, and I bet there is a vim wizard that has written something to
> let vim hide Doxygen comment.
If you hide them, there is little point in having them at all. It's
much more helpful for development to document the internal usage and
peculiarities of a function than to put end user documentation into it.
Everything that makes code hard to read, understand or navigate is
clutter IMO. And end user documentation adds to all of those things.
> > So while the benefits might be tempting, they usually don't turn
> > out as
> > benefits that much. The only thing that I would like to see (that
> > doxygen does IIRC) is to be able to identify missing or wrong
> > function
> > signatures.
> Just to sum up what I think it takes to have the API documentation in
> docbook.
> - A script that extracts classes, members, functions, data, globals,
> etc. and verifies whether or not they are in the docbook source
> - A script that keeps the source up to date (automatically add new
> members, delete old members, etc) and that warns that things have
> changed or that things are undocumented.
> - A script that creates thousands of entities to be able to easily
> refer to other functions, both in class and in other classes.
Isn't that just one script?
> We probably also need to use entities and/or scripts to keep the
> internal structure in a consisten way.
>
> That's what I call clutter. Especially if doxygen does the bulk of
> things.
If it can be used to validate (external) documentation by utilizing
sources/headers that would certainly be nice. I didn't like the (few)
doxygen docs I've seen so far, but they could probably be improved,
too. Last time I looked, doxygen's XML output was pretty poor, though.
Writing a script that parses XML files to match (and create) Docbook
sources sounds similar in difficulty as hacking Doxygen to produce
proper Docbook output. But since we have more possibilities with
Docbook regarding things like grouping functions logically, I'd prefer
to go that way.
Bye,
Axel.
Other related posts:
