Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4802498

stddoclet: Enable @param to validate & document multiple parameters: @param x,y

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Unresolved
    • Icon: P4 P4
    • tbd
    • 1.4.0
    • tools
    • Fix Understood
    • generic
    • other

      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,&nbsp;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.

            Unassigned Unassigned
            dkramersunw Douglas Kramer (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Imported:
              Indexed: