JDK-4807571 : Fix bad @param tags in javax.swing.plaf
  • Type: Bug
  • Component: docs
  • Sub-Component: guides
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • OS: generic
  • CPU: generic
  • Submitted: 2003-01-24
  • Updated: 2006-04-11
  • Resolved: 2006-04-11
Related Reports
Duplicate :  
Description
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.



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

Comments
EVALUATION Fixed by 6383723: Clean up javadoc warnings in AWT, Swing, and 2D classes
11-04-2006

WORK AROUND Name: dk30142 Date: 01/23/2003 ======================================================================
11-06-2004