[openbeos] Re: BeBook license

"Niels Reedijk" <n.reedijk@xxxxxxxxx> wrote:
> 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'.

At least, it has been decided to *not* place it in the headers - that's 
really not the right location IMHO. Anyway, if you put it in the source 
or in a dedicated file is up to the developer in question.

> > 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. 

That's right, but as we won't have as many changes to the R5 API it 
probably doesn't matter for now; and anyway that's an argument to put 
the documentation next to the code, not in the headers - you can't 
change the headers (because that would break binary compatibility), but 
you can change the implementation at any point, like new return codes 
or whatever.
But yes, we will have to make sure that our documentation is not as 
outdated and incorrect as the BeBook - which is good overall, but far 
from perfect. I like the Javadoc style of comments, and I like the 
documentation it puts out, very usable, very much up to date.

Adios...
   Axel.

Other related posts: