[openbeos] Re: BeBook license
- From: François Revol <revol@xxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Tue, 17 Jun 2003 10:46:45 +0200 (CEST)
En réponse à Matthijs Hollemans <matthijs@xxxxxxxxxxxxxxxxxxx>:
> > 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.
>
Anyone here knows docbook or texinfo ?
François.
Other related posts:
