Javadoc 1.4.x cannot handle documenting multiple parameter names that
logically group together, such as x, y coordinates. This would
be a more intelligent way of documenting parameters than we currently allow.
Javadoc had this ability in all previous versions, but lost it in
1.4.0 when we added parameter name validation. This request is to
re-institute this capability with validation.
I would recommend the separator to be a comma and a normal-space
where the comma would indicate to the parser to continue reading
for more terms. The space after the comma should be optional.
/**
* @param x,y the coordinates of this <code>GlyphVector</code>
*/
public abstract Shape getOutline(float x, float y);
which should print as:
Parameters:
x, y the coordinates of this GlyphVector
Notice the doclet Writer class would add the space after the comma, as shown.
Here's the same example with the space after the comma:
/**
* @param x, y the coordinates of this <code>GlyphVector</code>
*/
public abstract Shape getOutline(float x, float y);
Here's another real example with more than 2 parameters:
/**
* Constructs a new <code>AffineTransform</code> from 6 floating point
* values representing the 6 specifiable entries of the 3x3
* transformation matrix.
*
* @param m00,m01,m02,m10,m11,m12
* the 6 floating point values that compose the 3x3 transformation matrix
*/
public AffineTransform(float m00, float m10,
float m01, float m11,
float m02, float m12)
FYI, prior to 1.4.0, authors could use an HTML non-breaking space in
the first term, as shown next. There are about 191 such @param tags in
java.awt.geom and 8 in java.awt.font.
/**
* ...
* @param x, y the coordinates of this <code>GlyphVector</code>.
* ...
*/
public abstract Shape getOutline(float x, float y);
This RFE is related to, but independent of, the bug:
4802275: @param should be printed even if first argument is incorrect
In other words, that bug needs to be fixed whether or not this RFE is implemented.
logically group together, such as x, y coordinates. This would
be a more intelligent way of documenting parameters than we currently allow.
Javadoc had this ability in all previous versions, but lost it in
1.4.0 when we added parameter name validation. This request is to
re-institute this capability with validation.
I would recommend the separator to be a comma and a normal-space
where the comma would indicate to the parser to continue reading
for more terms. The space after the comma should be optional.
/**
* @param x,y the coordinates of this <code>GlyphVector</code>
*/
public abstract Shape getOutline(float x, float y);
which should print as:
Parameters:
x, y the coordinates of this GlyphVector
Notice the doclet Writer class would add the space after the comma, as shown.
Here's the same example with the space after the comma:
/**
* @param x, y the coordinates of this <code>GlyphVector</code>
*/
public abstract Shape getOutline(float x, float y);
Here's another real example with more than 2 parameters:
/**
* Constructs a new <code>AffineTransform</code> from 6 floating point
* values representing the 6 specifiable entries of the 3x3
* transformation matrix.
*
* @param m00,m01,m02,m10,m11,m12
* the 6 floating point values that compose the 3x3 transformation matrix
*/
public AffineTransform(float m00, float m10,
float m01, float m11,
float m02, float m12)
FYI, prior to 1.4.0, authors could use an HTML non-breaking space in
the first term, as shown next. There are about 191 such @param tags in
java.awt.geom and 8 in java.awt.font.
/**
* ...
* @param x, y the coordinates of this <code>GlyphVector</code>.
* ...
*/
public abstract Shape getOutline(float x, float y);
This RFE is related to, but independent of, the bug:
4802275: @param should be printed even if first argument is incorrect
In other words, that bug needs to be fixed whether or not this RFE is implemented.