[sldev] Viewer documentation & doxygen

[Carlo Wood]

While this could be true for headerfiles, I'm inclined to think
that in the case of source files it's better to keep the documentation
close to the function for the sake of keeping it up to date.

If documentation is put somewhere at the end of a file, it
might as well be on a wiki-- it's less likely that people will
take the time to keep it updated, imho. It is also harder
to find the documentation while browsing the source code
itself.

The concern about merge conflicts are valid for headers, but
not really for source files, since in general there will always
be a context of 3 lines inbetween the documentation and
the functions.

A class has obviously inline functions, which have to be
documented in the headerfile. But inline functions are
usually very small and will not change much; therefore
it might be sufficient to add their documentation at
the end of the headerfile; also, small inline functions
are often understandable if need be without documentation.

On Wed, Apr 08, 2009 at 09:12:04AM +0100, Robin Cornelius wrote:
> I've had some private feedback that the doxygen markup is too
> intrusive as comments inline in the code and it was suggested that
> these could be added at the end of a file.
> 
> Actually this is a win-win. The comments are not interrupting anyones
> overview of the code reading it in a straight code editor . But the
> biggest win is merge conflicts. If the documentation is all contained
> after the code it would be less likely to be/cause merge conflicts due
> to small code changes etc and makes it a whole lot easier for 3rd
> parties to contribute documentation without someone having to hand
> rebase because the code reference points in the diff have changed.
> 
> Robin

-- 
Carlo Wood <carlo at alinoe.com>