Suggestion for DDoc - share parameter descriptions

[Victor Nakoryakov]

nick wrote:
> 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!

Absolutely disagree...


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

...more than common practice is to write thin-wrap methods like.

void setColor(Color c)
{
//...
}

void setColor(float r, float g, float b)
{
setColor( Color(r,g,b) );
}

this helps to avoid redundant code like:

setColor( Color(0,0,0) ); // black
...
setColor( Color(1, 1, 1) ); // white
...
setColor( Color(0,0,0) ); // black
...
setColor( Color(1, 1, 1) ); // white

Using mathematical induction, we can show that such OOP-ish can lead to 
constructs like:

setMatrix( Matrix4(Matrix3(Vector3(1,0,0), Vector3(0,1,0), 
Vector3(0,0,1)), Vector3(1,2,3)) );

instead of:

setMatrix( Matrix4(
1,0,0,1,
0,1,0,2,
0,1,0,3,
0,0,0,1 ));

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


+1 for syntax

Params:
r,g,b = blah blah blah

-- 
Victor (aka nail) Nakoryakov
nail-mail [at] mail.ru

Krasnoznamensk, Moscow, Russia