Re: Doxygen comments in C++ source

Anyway, I don't want to impose my opinion, just state it. You're free to do
things however you like.

On Wed, Feb 7, 2018 at 12:02 PM, James McCartney <[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
>



-- 
--- james mccartney