[sldev] Viewer documentation & doxygen

[Robin Cornelius]

On Wed, Apr 8, 2009 at 6:49 AM, Robin Cornelius
<robin.cornelius at gmail.com> wrote:

> heh, of cause not ;-p
>> I was addressing some previous concerns about manpower and effort this
> would take when this subject was broached previously at Rob's office
> hour (no reference). My comments were directed the other side of the
> firewall where I suspect LL devs are going to have to add it ad-hoc
> rather than sit down and just document due to limited resources. If
> people from this side of the firewall could contribute documentation I
> see that as a big win for all concerned.
>


Replying to myself in the best possible etiquette,

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