[openbeos] Re: BeBook license
- From: "Matthijs Hollemans" <matthijs@xxxxxxxxxxxxxxxxxxx>
- To: <openbeos@xxxxxxxxxxxxx>
- Date: Tue, 17 Jun 2003 09:36:30 +0200
> I believe the best way to generate the Be Book is with Doxygen.
> This is simply the best solution, as it provides easy means to
> maintain the documentation at the core: the header files. [...]
I think this was discussed before. The problem with Doxygen is that the
doc comments clutter up the headers, and it was more-or-less decided
that we would not do this.
The alternative is to put the comments in the code. Opinions vary on
this. Personally, I think having doc comments in the code distracts from
the readability of the actual code. This is not a big deal when the
comments are sparse, but in the case of the BeBook, the comments will
often be larger than the source code itself.
Third possibility is to put the Doxygen comments in separate files,
which I did for the Midi Kit documentation, see /current/docs/user.
However, Doxygen has a number of issues too. For example, I don't think
it handles translations to other languages. (And where would you put
them... also in the source code?) Actually, I don't really think that it
is a big deal to have a translated BeBook, but others may disagree.
-Matthijs
Other related posts:
