Re: Doxygen comments in C++ source

> I hate Doxygen.

I'm not here to argue about this. What I want is a process that makes it
easy to:
- incrementally and reliably improve documentation
- work with a legacy codebase
- organized in multiple directories
- written in many styles
- is in a reasonably flexible format, i.e. can be hooked into other tools
and easily cross-referenced with source code

Doxygen is the only tool I know that satisfies all these things and has
existing presence in the codebase, which is why I considered it the
"default" here. But if you don't like Doxygen, provide an actual proposal
for what you do want, because I'll happily work with any tools and
processes that satisfy all of the above.

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

When the function is a 500+ LOC behemoth with no unit tests and several
single-letter-name variables, that's simply not realistic advice.

-Brian

On Wed, Feb 7, 2018 at 3:02 PM, <[email protected]> wrote:

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