Re: Doxygen comments in C++ source

I'm long out of active development of SC, but I'll throw in my curmudgeonly
opinion here. I hate Doxygen. All it does is give you a laundry list of
classes and methods that is mostly useless for figuring out how a framework
is architected. And for that you get junked up source code that is harder
to read. There is no substitute for taking the care to write a separate
document that explains a class, method or framework. Once you have that,
you don't need Doxygen. When you are coding and just sticking in inline
comments, you are not in the same frame of mind and do not have the context
that you have when you are writing documentation.

Also, by following the principle of: "if you find yourself documenting a
piece of code within a function, stop, take that code out into a new
function whose name is the text of the comment", you will find you often
don't need to document functions. They say what they do.
Then write a help file.


On Wed, Feb 7, 2018 at 11:02 AM, <[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.
>
> Use of these comments was already present (scarcely) in some places in the
> codebase before I started adding it, so this is not entirely out of the
> blue. I've worked out an addition to our Travis script that automatically
> creates the docs and posts them to github-pages:
>
> https://github.com/brianlheim/supercollider/pull/3
>
> You can see the result of that here:
>
> http://www.brianlheim.com/supercollider/index.html
>
> The Doxygen/Javadoc format is widely used and can be parsed by other
> documentation generation tools such as standardese (
> https://github.com/foonathan/standardese). Doxygen XML output itself can
> also be used by other generation tools.
>
> -Brian
>



-- 
--- james mccartney