[openbeos] Re: BeBook license

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: