[openbeos] Re: doxygen basics
- From: "Erik Jakowatz" <erik@xxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Thu, 13 Dec 2001 01:31:41 -0800
I'm really torn on this subject, so much so that it's been sort of
holding some things up for my team. =( I *really* like the idea of
embedding our documentation in the source -- to me this seems key to any
hope of keeping the docs up-to-date. And, echoing what Michael said, I
*really* like the free-beer nature of doxygen.
Unfortunately, I have to break ranks with what other people are
expressing and say that I *hate* it's output. And I do mean *hate*. I
honestly don't think I could construct a more context-free way to
organize documentation -- the strict hierarchy in the standard output
serves to chop everything into little pieces that are hard to relate to
each other. I personally really like the BeBook's format -- not the
flash, but the overall scheme of organization. You can almost read the
docs straight through from start to finish like a text book!
Documentation for a given class is all together, grouped by functional
area (constructors/destructor, hook functions, static functions, etc.),
with closely related functions documented together in one entry, which
really facilitates documenting the *relationship* between the functions.
The doxygen output that I've seen thus far doesn't even come close to
that kind of readability, and I feel very strongly that documentation of
public APIs should be *extremely* friendly (wouldn't hurt for private
APIs, either). After all, it was reading Be's online docs for R3 that
convinced me that I just *had* to develop for BeOS.
Ithamar Adema and I are working together (which is to say he's doing a
lot of work and I'm being very picky about it ;) to see if we can't make
doxygen give us docs with BeBook-like organization. There are other
freely available (and open source) doc generation tools out there that
use JavaDoc-like commenting, and if doxygen can't be made to behave,
perhaps one of those other tools can. ;)
I'll keep you all posted on our progress.
e
>Does anyone object?
>I have never used it, but the price is certainly right. :-)
>
>
>>Matt McMinn wrote:
>>>
>>>I've got the promised article on the basics of doxygen up at
>>>
>>>http://home.earthlink.net/~melfina/doxygen.htm
>>>
>>>Please keep in mind while flaming that this is the first time I've
used
>>>doxygen myself, so it may not be complete, but it should be a good
>>>start.
>>>
>>>Matt
>>>
>>
>>Wow! Thanks Matt. Doxygen looks sweet indeed.
>>
>>So,.. is the OBOS crew *officially* using it?
>>
>>My 2 cents:
>>-looks easy to use
>>-gives nice copious output of what it's doing
>>-seems actively developed
>>-gives LaTeX output (yeah!)
>>-nice support (up-to-date website, detailed manual)
Data is not information, and information is not knowledge: knowledge is
not understanding, and understanding is not wisdom.
- Philip Adams
Other related posts:
