Suggestion for DDoc - share parameter descriptions

[nick]

Lionello Lunesu wrote:
> nick wrote:
>> I am not sure about the best way to do this, but some sort of
>> "ditto"-like feature may be good.
>>
>> The flip side of the argument is that you should probably have a vec3
>> class/template for handling this sort of situation. This kind of logic
>> would apply to having pretty much any number of similar parameters.
>> The logic being: If parameters belong together, then group them together
>> and document the group.
>>
> 
> But at some point you'll have to call a function taking r,g,b.. And
> document it :)
> 
> L.

I think that there isn't enough justification for putting in this
feature. Every extra feature makes learning a tool more difficult, and
if you write clean code you shouldn't have very many similar parameters.
So, having this feature will encourage writing bad code!

We'll use Color as an example...

Given that you group RGB into a class Color, You still have to document
(byte r, byte g, byte b) in the constructor for the class Color.
There is only one constructor where there are lots of methods that use a
Color. So that ONE time you could use a handy approach similar to
doxygen's.

/** doxygen style
*
* @param r, g, b	: red, green, blue components.
*
* ... More description on how r, g, b are used...
*
*/

But having to expand the @param line to:

* @param r : red
* @param g : green
* @param b : blue
* ... More description on how r, g, b are used...

isn't going to kill you. If you are duplicating comments all over the
place, maybe you will be driven to refactor your code a little to avoid
duplication. So, in the end, the lack of a feature cleans up your code =).