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

Fix bad @param tags in javax.swing.plaf

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Duplicate
    • Icon: P4 P4
    • None
    • 1.4.0
    • docs
    • None
    • generic
    • generic

      Methods in javax.swing.plaf and its subpackages are missing
      @param tags and one method has a bad first argument to @param.

      Here are the errors -- fixes are underlined with carets ("^^^"):

      ----------------------------
      javax.swing.plaf.ListUI

        Missing @param for list, index1 and index2. Unknown @param index.

          /**
           * Returns the bounds of the specified item in JList
                     a bounding box items
                     ^^^^^^^^^^^^^^ ^^^^^
           * coordinates, null if either index isn't valid.
                                  ^^^^^^
           *
           * @param list The JList the ListUI is currently installed on.
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @param index The index of the JList cell.
                    index1 Index of the first model item to get the bounds of
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @param index2 Index of the last model item to get the bounds of
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @return The bounds of the index'th cell.
                     The bounding box containing the items
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           */
          public abstract Rectangle getCellBounds(JList list, int index1, int index2);

      Add "@param list" shown above for all the ListUI methods that take a JList
      (it appears none of them have this)

      -----------------------
      javax.swing.plaf.TextUI

        Missing @param for "t", unknown @param for "a" (are they the same?)
        Missing b and biasRet

          /**
           * Provides a way to determine the next visually represented model
           * location that one might place a caret. Some views may not be visible,
           * they might not be in the same order found in the model, or they just
           * might not allow access to some of the locations in the model.
           *
           * @param t The JTextComponent the TextUI is currently installed on.
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @param pos the position to convert >= 0
           * @param a the allocated region to render into
           ^^^^^^^^^^^^^ DELETE ABOVE LINE ^^^^^^^^^^^^^^
           * @param b either <code>Position.Bias.Forward</code>
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * or <code>Position.Bias.Backward</code>
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @param direction the direction from the current position that can
           * be thought of as the arrow keys typically found on a keyboard.
           * This may be SwingConstants.WEST, SwingConstants.EAST,
           * SwingConstants.NORTH, or SwingConstants.SOUTH.
           * @param biasRet either <code>Position.Bias.Forward</code>
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * or <code>Position.Bias.Backward</code> is returned as the
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * zero-th element of this array
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           * @return the location within the model that best represents the next
           * location visual position.
           * @exception BadLocationException
           * @exception IllegalArgumentException for an invalid direction
           */
          public abstract int getNextVisualPositionFrom(JTextComponent t,
                               int pos, Position.Bias b,
                               int direction, Position.Bias[] biasRet)
                               throws BadLocationException;

      Add "@param t" list shown above for all TextUI methods that
      take a TextUI parameter.

      ----------------------------------
      javax.swing.plaf.basic.BasicTextUI

        Same problems & solutions here:

          /**
           * Provides a way to determine the next visually represented model
           * location that one might place a caret. Some views may not be visible,
           * they might not be in the same order found in the model, or they just
           * might not allow access to some of the locations in the model.
           *
           * @param pos the position to convert >= 0
           * @param a the allocated region to render into
           * @param direction the direction from the current position that can
           * be thought of as the arrow keys typically found on a keyboard.
           * This may be SwingConstants.WEST, SwingConstants.EAST,
           * SwingConstants.NORTH, or SwingConstants.SOUTH.
           * @return the location within the model that best represents the next
           * location visual position.
           * @exception BadLocationException
           * @exception IllegalArgumentException for an invalid direction
           */
          public int getNextVisualPositionFrom(JTextComponent t, int pos,
                          Position.Bias b, int direction, Position.Bias[] biasRet)
                          throws BadLocationException{


      NOTE: Prior to 1.4.0, javadoc did not check that the first argument to
      @param was a valid parameter name, and printed it even if it was wrong.
      In 1.4.x, javadoc checks the first argument to ensure it matches a
      parameter name, and if not, prints a warning. In addition it
      does NOT print the parameter term if the term is wrong, meaning
      important parts of the spec have disappeared.



      ======================================================================

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

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: