[openbeos] Re: BeBook license
- From: "Niels Reedijk" <n.reedijk@xxxxxxxxx>
- To: <openbeos@xxxxxxxxxxxxx>
- Date: Tue, 17 Jun 2003 14:19:44 +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.
I wasn't there when it was discussed, but I don't agree that it clutters
up the headers. For example:
http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdelibs/kdecore/kcompletion.h?r
ev=1.66&content-type=text/x-cvsweb-markup . Also, with the proper code
highlighting, you will clearly see what documentation is and what
comment is. And to be honest: I've never looked inside a header to see
the API, rather I've looked at the docs. So the header remains to the
compiler and the OBOS developer only. Please note that I have no clue
how far the place of documentation is 'decided'.
> 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.
That's more than true. Also, not everything is present in the source
files (for example: inline functions).
> Third possibility is to put the Doxygen comments in separate files,
> which I did for the Midi Kit documentation, see /current/docs/user.
It may keep the headers 'clean', however, this means essentially
maintaining the header in two places. When you put documentation in
headers, you will immediately see which entities are undocumented. If
you add new methods, you will instantly see that these still need to be
undocumented. Maintaining the documentation in separate files actually
makes the documenting process more tedious.
Niels
Other related posts:
