Sometimes, you have several parameters that work together, as components of an aggregate value, perhaps.  In this case, it seems redundant to write


/**
Makes a spoony color.

Params:
    r = The red component of the color.
    g = The green component of the color.
    b = the blue component of the color.
*/
uint spoon(int r, int g, int b)
{

}


Instead, it'd be convenient to write something like


/**
Makes a spoony color.

Params:
    r = The red, green, and blue components of the color.
    g = ditto
    b = ditto
*/


Which follows the current convention for using the same documentation for multiple items.

Or even better:


/**
Makes a spoony color.

Params:
    r, g, b = The red, green, and blue components of the color.
*/


A niche feature, I know, but it's just for fun.

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.


Jarrett Billingsley wrote:
> Sometimes, you have several parameters that work together, as components of an aggregate value, perhaps.  In this case, it seems redundant to write
> 
> 
> /**
> Makes a spoony color.
> 
> Params:
>     r = The red component of the color.
>     g = The green component of the color.
>     b = the blue component of the color.
> */
> uint spoon(int r, int g, int b)
> {
> 
> }
> 
> 
> Instead, it'd be convenient to write something like
> 
> 
> /**
> Makes a spoony color.
> 
> Params:
>     r = The red, green, and blue components of the color.
>     g = ditto
>     b = ditto
> */
> 
> 
> Which follows the current convention for using the same documentation for multiple items.
> 
> Or even better:
> 
> 
> /**
> Makes a spoony color.
> 
> Params:
>     r, g, b = The red, green, and blue components of the color.
> */
> 
> 
> A niche feature, I know, but it's just for fun.
> 
> 

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.

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

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