www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Suggestion for DDoc - share parameter descriptions

reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
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.
May 18 2006
parent reply nick <nick.atamas gmail.com> writes:
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.
May 18 2006
parent reply Lionello Lunesu <lio lunesu.remove.com> writes:
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.
May 19 2006
parent reply nick <nick.atamas gmail.com> writes:
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 =).
May 19 2006
parent Victor Nakoryakov <nail-mail mail.ru> writes:
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
May 22 2006