Re: Doxygen comments in C++ source

On 2018-02-07 11:02, [email protected] wrote:
> Hey all,
> 
> In my last few PRs that modified C++ source, I added Doxygen comments
> for the functions I added/modified. Since the codebase is somewhat
> lacking in documentation, I was wondering if we could establish some
> organizational rules about this. Specifically:
> 
> - Any new C++ code must have Doxygen comments
> - Any changes to existing C++ code must add Doxygen comments if
> they're not present
> 
> - This applies to all documentable elements - functions, data (such as
> class members and globals), enums, classes, and files when appropriate
> 
> - In header (hpp) files, document the element according to its usage
> (preconditions, parameters, return value)
> 
> - In implementation (cpp) files, document implementation details if
> necessary
> 
> - If the element only exists in an implementation file, document both
> 
> - If the element is trivial and can be determined from name alone, it
> doesn't necessarily need to be documented.
> 
> Ideally, over time, this will lead to the most commonly touched parts
> of the codebase becoming well-documented, making them easier to
> understand and modify in the future.

hi brian,

my view is this: good code with prose documentation > good code with 
generated documentation > good code with no documentation > bad code 
with generated documentation > bad code with no documentation. in an 
ideal world, all our C++ is pristine and documented with comprehensive 
articles. in practice we can settle for lesser alternatives in the 
interest of saving work.

so i guess my proposal would be, write Doxygen comments if you really 
feel like it, but with the understanding that it's temporary. either 
way, code quality comes first.

you, josh, and i have agreed on one thing though: documentation of 
sclang/scsynth source should be done in an established documentation 
system, not SCDoc. i would like to see all scsynth development tooling 
to be self-contained with no dependencies on sclang. (there are vague 
plans to phase out SCDoc anyway, but that's a discussion for another 
thread) we could use Doxygen for this, and i'm also partial to Sphinx if 
we don't mind a Python dependency.


nathan

_______________________________________________
sc-dev mailing list

info (subscription, etc.): http://www.birmingham.ac.uk/facilities/ea-studios/research/supercollider/mailinglist.aspx
archive: http://www.listarc.bham.ac.uk/marchives/sc-dev/
search: http://www.listarc.bham.ac.uk/lists/sc-dev/search/