From 4bb7d288435d68957858240432aa6a14ff5bca4e Mon Sep 17 00:00:00 2001 From: Dmitriy Ermashov Date: Fri, 16 May 2014 17:45:35 +0400 Subject: [PATCH] 8042089: Fix doclint warnings from javax.swing.tree and javax.swing.undo packages Reviewed-by: alexsch --- .../javax/swing/tree/AbstractLayoutCache.java | 7 +++ .../swing/tree/DefaultMutableTreeNode.java | 7 +++ .../swing/tree/DefaultTreeCellEditor.java | 8 ++- .../swing/tree/DefaultTreeCellRenderer.java | 42 ++++++++++++++ .../javax/swing/tree/DefaultTreeModel.java | 26 +++++++++ .../swing/tree/DefaultTreeSelectionModel.java | 16 ++++++ .../javax/swing/tree/MutableTreeNode.java | 11 ++++ .../classes/javax/swing/tree/RowMapper.java | 4 ++ .../javax/swing/tree/TreeCellRenderer.java | 9 ++- .../classes/javax/swing/tree/TreeModel.java | 5 +- .../classes/javax/swing/tree/TreeNode.java | 16 ++++++ .../classes/javax/swing/tree/TreePath.java | 6 +- .../javax/swing/tree/TreeSelectionModel.java | 55 +++++++++++++++---- .../javax/swing/undo/CompoundEdit.java | 4 ++ .../javax/swing/undo/StateEditable.java | 4 ++ .../classes/javax/swing/undo/UndoManager.java | 2 + .../javax/swing/undo/UndoableEditSupport.java | 6 ++ 17 files changed, 212 insertions(+), 16 deletions(-) diff --git a/jdk/src/share/classes/javax/swing/tree/AbstractLayoutCache.java b/jdk/src/share/classes/javax/swing/tree/AbstractLayoutCache.java index c0e474e26cd..cbb6ed09530 100644 --- a/jdk/src/share/classes/javax/swing/tree/AbstractLayoutCache.java +++ b/jdk/src/share/classes/javax/swing/tree/AbstractLayoutCache.java @@ -149,6 +149,8 @@ public abstract class AbstractLayoutCache implements RowMapper { * Returns the height of each row. If the returned value is less than * or equal to 0 the height for each row is determined by the * renderer. + * + * @return the height of each row */ public int getRowHeight() { return rowHeight; @@ -263,6 +265,9 @@ public abstract class AbstractLayoutCache implements RowMapper { /** * Returns true if the value identified by row is currently expanded. + * + * @param path TreePath to check + * @return whether TreePath is expanded */ public abstract boolean isExpanded(TreePath path); @@ -496,6 +501,8 @@ public abstract class AbstractLayoutCache implements RowMapper { /** * Returns true if the height of each row is a fixed size. + * + * @return whether the height of each row is a fixed size */ protected boolean isFixedRowHeight() { return (rowHeight > 0); diff --git a/jdk/src/share/classes/javax/swing/tree/DefaultMutableTreeNode.java b/jdk/src/share/classes/javax/swing/tree/DefaultMutableTreeNode.java index c33599064e2..2e451400d25 100644 --- a/jdk/src/share/classes/javax/swing/tree/DefaultMutableTreeNode.java +++ b/jdk/src/share/classes/javax/swing/tree/DefaultMutableTreeNode.java @@ -534,6 +534,7 @@ public class DefaultMutableTreeNode implements Cloneable, * Returns true if and only if aNode is in the same tree * as this node. Returns false if aNode is null. * + * @param aNode node to find common ancestor with * @see #getSharedAncestor * @see #getRoot * @return true if aNode is in the same tree as this node; @@ -638,6 +639,8 @@ public class DefaultMutableTreeNode implements Cloneable, * Returns the user object path, from the root, to get to this node. * If some of the TreeNodes in the path have null user objects, the * returned path will contain nulls. + * + * @return the user object path, from the root, to get to this node */ public Object[] getUserObjectPath() { TreeNode[] realPath = getPath(); @@ -828,6 +831,7 @@ public class DefaultMutableTreeNode implements Cloneable, * Modifying the tree by inserting, removing, or moving a node invalidates * any enumerations created before the modification. * + * @param ancestor the node to start enumeration from * @see #isNodeAncestor * @see #isNodeDescendant * @exception IllegalArgumentException if ancestor is @@ -848,6 +852,7 @@ public class DefaultMutableTreeNode implements Cloneable, * Returns true if aNode is a child of this node. If * aNode is null, this method returns false. * + * @param aNode the node to determinate whether it is a child * @return true if aNode is a child of this node; false if * aNode is null */ @@ -906,6 +911,7 @@ public class DefaultMutableTreeNode implements Cloneable, * aChild and is O(n) where n is the number of children; to * traverse the entire array of children, use an enumeration instead. * + * @param aChild the child node to look for next child after it * @see #children * @exception IllegalArgumentException if aChild is * null or is not a child of this node @@ -938,6 +944,7 @@ public class DefaultMutableTreeNode implements Cloneable, * performs a linear search of this node's children for aChild * and is O(n) where n is the number of children. * + * @param aChild the child node to look for previous child before it * @exception IllegalArgumentException if aChild is null * or is not a child of this node * @return the child of this node that immediately precedes diff --git a/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellEditor.java b/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellEditor.java index f6c2559cd99..15c645af8fd 100644 --- a/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellEditor.java +++ b/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellEditor.java @@ -405,7 +405,9 @@ public class DefaultTreeCellEditor implements ActionListener, TreeCellEditor, /** * Returns true if event is a MouseEvent * and the click count is 1. - * @param event the event being studied + * + * @param event the event being studied + * @return whether {@code event} should starts the editing timer */ protected boolean shouldStartEditingTimer(EventObject event) { if((event instanceof MouseEvent) && @@ -433,7 +435,9 @@ public class DefaultTreeCellEditor implements ActionListener, TreeCellEditor, * Returns true if event is null, * or it is a MouseEvent with a click count > 2 * and inHitRegion returns true. + * * @param event the event being studied + * @return whether editing can be started for the given {@code event} */ protected boolean canEditImmediately(EventObject event) { if((event instanceof MouseEvent) && @@ -513,6 +517,8 @@ public class DefaultTreeCellEditor implements ActionListener, TreeCellEditor, /** * Creates the container to manage placement of * editingComponent. + * + * @return new Container object */ protected Container createContainer() { return new EditorContainer(); diff --git a/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellRenderer.java b/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellRenderer.java index e24ccd978f3..c8784e93c43 100644 --- a/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellRenderer.java +++ b/jdk/src/share/classes/javax/swing/tree/DefaultTreeCellRenderer.java @@ -234,6 +234,9 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the default icon, for the current laf, that is used to * represent non-leaf nodes that are expanded. + * + * @return the default icon, for the current laf, that is used to + * represent non-leaf nodes that are expanded. */ public Icon getDefaultOpenIcon() { return DefaultLookup.getIcon(this, ui, "Tree.openIcon"); @@ -242,6 +245,9 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the default icon, for the current laf, that is used to * represent non-leaf nodes that are not expanded. + * + * @return the default icon, for the current laf, that is used to + * represent non-leaf nodes that are not expanded. */ public Icon getDefaultClosedIcon() { return DefaultLookup.getIcon(this, ui, "Tree.closedIcon"); @@ -250,6 +256,9 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the default icon, for the current laf, that is used to * represent leaf nodes. + * + * @return the default icon, for the current laf, that is used to + * represent leaf nodes. */ public Icon getDefaultLeafIcon() { return DefaultLookup.getIcon(this, ui, "Tree.leafIcon"); @@ -257,6 +266,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the icon used to represent non-leaf nodes that are expanded. + * + * @param newIcon the icon to be used for expanded non-leaf nodes */ public void setOpenIcon(Icon newIcon) { openIcon = newIcon; @@ -264,6 +275,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the icon used to represent non-leaf nodes that are expanded. + * + * @return the icon used to represent non-leaf nodes that are expanded */ public Icon getOpenIcon() { return openIcon; @@ -271,6 +284,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the icon used to represent non-leaf nodes that are not expanded. + * + * @param newIcon the icon to be used for not expanded non-leaf nodes */ public void setClosedIcon(Icon newIcon) { closedIcon = newIcon; @@ -279,6 +294,9 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the icon used to represent non-leaf nodes that are not * expanded. + * + * @return the icon used to represent non-leaf nodes that are not + * expanded */ public Icon getClosedIcon() { return closedIcon; @@ -286,6 +304,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the icon used to represent leaf nodes. + * + * @param newIcon icon to be used for leaf nodes */ public void setLeafIcon(Icon newIcon) { leafIcon = newIcon; @@ -293,6 +313,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the icon used to represent leaf nodes. + * + * @return the icon used to represent leaf nodes */ public Icon getLeafIcon() { return leafIcon; @@ -300,6 +322,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the color the text is drawn with when the node is selected. + * + * @param newColor color to be used for text when the node is selected */ public void setTextSelectionColor(Color newColor) { textSelectionColor = newColor; @@ -307,6 +331,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the color the text is drawn with when the node is selected. + * + * @return the color the text is drawn with when the node is selected */ public Color getTextSelectionColor() { return textSelectionColor; @@ -314,6 +340,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the color the text is drawn with when the node isn't selected. + * + * @param newColor color to be used for text when the node isn't selected */ public void setTextNonSelectionColor(Color newColor) { textNonSelectionColor = newColor; @@ -321,6 +349,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the color the text is drawn with when the node isn't selected. + * + * @return the color the text is drawn with when the node isn't selected. */ public Color getTextNonSelectionColor() { return textNonSelectionColor; @@ -328,6 +358,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the color to use for the background if node is selected. + * + * @param newColor to be used for the background if the node is selected */ public void setBackgroundSelectionColor(Color newColor) { backgroundSelectionColor = newColor; @@ -336,6 +368,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the color to use for the background if node is selected. + * + * @return the color to use for the background if node is selected */ public Color getBackgroundSelectionColor() { return backgroundSelectionColor; @@ -343,6 +377,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the background color to be used for non selected nodes. + * + * @param newColor color to be used for the background for non selected nodes */ public void setBackgroundNonSelectionColor(Color newColor) { backgroundNonSelectionColor = newColor; @@ -350,6 +386,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the background color to be used for non selected nodes. + * + * @return the background color to be used for non selected nodes. */ public Color getBackgroundNonSelectionColor() { return backgroundNonSelectionColor; @@ -357,6 +395,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Sets the color to use for the border. + * + * @param newColor color to be used for the border */ public void setBorderSelectionColor(Color newColor) { borderSelectionColor = newColor; @@ -364,6 +404,8 @@ public class DefaultTreeCellRenderer extends JLabel implements TreeCellRenderer /** * Returns the color the border is drawn. + * + * @return the color the border is drawn */ public Color getBorderSelectionColor() { return borderSelectionColor; diff --git a/jdk/src/share/classes/javax/swing/tree/DefaultTreeModel.java b/jdk/src/share/classes/javax/swing/tree/DefaultTreeModel.java index c3b9de2d698..550d8f6062b 100644 --- a/jdk/src/share/classes/javax/swing/tree/DefaultTreeModel.java +++ b/jdk/src/share/classes/javax/swing/tree/DefaultTreeModel.java @@ -105,6 +105,9 @@ public class DefaultTreeModel implements Serializable, TreeModel { * Sets whether or not to test leafness by asking getAllowsChildren() * or isLeaf() to the TreeNodes. If newvalue is true, getAllowsChildren() * is messaged, otherwise isLeaf() is messaged. + * + * @param newValue if true, getAllowsChildren() is messaged, otherwise + * isLeaf() is messaged */ public void setAsksAllowsChildren(boolean newValue) { asksAllowsChildren = newValue; @@ -125,6 +128,8 @@ public class DefaultTreeModel implements Serializable, TreeModel { /** * Sets the root to root. A null root implies * the tree is to display nothing, and is legal. + * + * @param root new value of tree root */ public void setRoot(TreeNode root) { Object oldRoot = this.root; @@ -231,6 +236,10 @@ public class DefaultTreeModel implements Serializable, TreeModel { * This will then message nodesWereInserted to create the appropriate * event. This is the preferred way to add children as it will create * the appropriate event. + * + * @param newChild child node to be inserted + * @param parent node to which children new node will be added + * @param index index of parent's children */ public void insertNodeInto(MutableTreeNode newChild, MutableTreeNode parent, int index){ @@ -247,6 +256,8 @@ public class DefaultTreeModel implements Serializable, TreeModel { * nodesWereRemoved to create the appropriate event. This is the * preferred way to remove a node as it handles the event creation * for you. + * + * @param node the node to be removed from it's parrent */ public void removeNodeFromParent(MutableTreeNode node) { MutableTreeNode parent = (MutableTreeNode)node.getParent(); @@ -266,6 +277,8 @@ public class DefaultTreeModel implements Serializable, TreeModel { /** * Invoke this method after you've changed how node is to be * represented in the tree. + * + * @param node the changed node */ public void nodeChanged(TreeNode node) { if(listenerList != null && node != null) { @@ -303,6 +316,9 @@ public class DefaultTreeModel implements Serializable, TreeModel { * Invoke this method after you've inserted some TreeNodes into * node. childIndices should be the index of the new elements and * must be sorted in ascending order. + * + * @param node parent node which children count been incremented + * @param childIndices indexes of inserted children */ public void nodesWereInserted(TreeNode node, int[] childIndices) { if(listenerList != null && node != null && childIndices != null @@ -322,6 +338,10 @@ public class DefaultTreeModel implements Serializable, TreeModel { * node. childIndices should be the index of the removed elements and * must be sorted in ascending order. And removedChildren should be * the array of the children objects that were removed. + * + * @param node parent node which childred were removed + * @param childIndices indexes of removed childs + * @param removedChildren array of the children objects that were removed */ public void nodesWereRemoved(TreeNode node, int[] childIndices, Object[] removedChildren) { @@ -334,6 +354,9 @@ public class DefaultTreeModel implements Serializable, TreeModel { /** * Invoke this method after you've changed how the children identified by * childIndicies are to be represented in the tree. + * + * @param node changed node + * @param childIndices indexes of changed children */ public void nodesChanged(TreeNode node, int[] childIndices) { if(node != null) { @@ -360,6 +383,8 @@ public class DefaultTreeModel implements Serializable, TreeModel { * Invoke this method if you've totally changed the children of * node and its children's children... This will post a * treeStructureChanged event. + * + * @param node changed node */ public void nodeStructureChanged(TreeNode node) { if(node != null) { @@ -374,6 +399,7 @@ public class DefaultTreeModel implements Serializable, TreeModel { * tree. * * @param aNode the TreeNode to get the path for + * @return an array of TreeNodes giving the path from the root */ public TreeNode[] getPathToRoot(TreeNode aNode) { return getPathToRoot(aNode, 0); diff --git a/jdk/src/share/classes/javax/swing/tree/DefaultTreeSelectionModel.java b/jdk/src/share/classes/javax/swing/tree/DefaultTreeSelectionModel.java index 73054ad0046..d1c152f19be 100644 --- a/jdk/src/share/classes/javax/swing/tree/DefaultTreeSelectionModel.java +++ b/jdk/src/share/classes/javax/swing/tree/DefaultTreeSelectionModel.java @@ -618,6 +618,9 @@ public class DefaultTreeSelectionModel implements Cloneable, Serializable, TreeS /** * Notifies all listeners that are registered for * tree selection events on this object. + * + * @param e the event that characterizes the change + * * @see #addTreeSelectionListener * @see EventListenerList */ @@ -920,6 +923,9 @@ public class DefaultTreeSelectionModel implements Cloneable, Serializable, TreeS /** * Returns true if the paths are contiguous, * or this object has no RowMapper. + * + * @param paths array of paths to check + * @return whether the paths are contiguous, or this object has no RowMapper */ protected boolean arePathsContiguous(TreePath[] paths) { if(rowMapper == null || paths.length < 2) @@ -968,6 +974,9 @@ public class DefaultTreeSelectionModel implements Cloneable, Serializable, TreeS * or the selection mode is DISCONTIGUOUS_TREE_SELECTION, or * adding the paths to the current selection still results in a * contiguous set of TreePaths. + * + * @param paths array of {@code TreePaths} to check + * @return whether the particular set of {@code TreePaths} can be added */ protected boolean canPathsBeAdded(TreePath[] paths) { if(paths == null || paths.length == 0 || rowMapper == null || @@ -1019,6 +1028,10 @@ public class DefaultTreeSelectionModel implements Cloneable, Serializable, TreeS * Returns true if the paths can be removed without breaking the * continuity of the model. * This is rather expensive. + * + * @param paths array of {@code TreePath} to check + * @return whether the paths can be removed without breaking the + * continuity of the model */ protected boolean canPathsBeRemoved(TreePath[] paths) { if(rowMapper == null || selection == null || @@ -1072,6 +1085,9 @@ public class DefaultTreeSelectionModel implements Cloneable, Serializable, TreeS * instances of PathPlaceHolder. * * @deprecated As of JDK version 1.7 + * + * @param changedPaths the vector of the changed paths + * @param oldLeadSelection the old selection path */ @Deprecated protected void notifyPathChange(Vector changedPaths, diff --git a/jdk/src/share/classes/javax/swing/tree/MutableTreeNode.java b/jdk/src/share/classes/javax/swing/tree/MutableTreeNode.java index 3c12d17e44b..98ad22ae4aa 100644 --- a/jdk/src/share/classes/javax/swing/tree/MutableTreeNode.java +++ b/jdk/src/share/classes/javax/swing/tree/MutableTreeNode.java @@ -42,22 +42,31 @@ public interface MutableTreeNode extends TreeNode /** * Adds child to the receiver at index. * child will be messaged with setParent. + * + * @param child node to be added + * @param index index of the receiver */ void insert(MutableTreeNode child, int index); /** * Removes the child at index from the receiver. + * + * @param index index of child to be removed */ void remove(int index); /** * Removes node from the receiver. setParent * will be messaged on node. + * + * @param node node to be removed from the receiver */ void remove(MutableTreeNode node); /** * Resets the user object of the receiver to object. + * + * @param object object to be set as a receiver */ void setUserObject(Object object); @@ -68,6 +77,8 @@ public interface MutableTreeNode extends TreeNode /** * Sets the parent of the receiver to newParent. + * + * @param newParent node to be set as parent of the receiver */ void setParent(MutableTreeNode newParent); } diff --git a/jdk/src/share/classes/javax/swing/tree/RowMapper.java b/jdk/src/share/classes/javax/swing/tree/RowMapper.java index 9c365dc17ea..a7b8da11738 100644 --- a/jdk/src/share/classes/javax/swing/tree/RowMapper.java +++ b/jdk/src/share/classes/javax/swing/tree/RowMapper.java @@ -41,6 +41,10 @@ public interface RowMapper * the same length as that passed in, and if one of the TreePaths * in path is not valid its entry in the array should * be set to -1. + * + * @param path array of TreePath to parse + * @return the rows that the TreePath instances in {@code path} are + * being displayed at */ int[] getRowsForPaths(TreePath[] path); } diff --git a/jdk/src/share/classes/javax/swing/tree/TreeCellRenderer.java b/jdk/src/share/classes/javax/swing/tree/TreeCellRenderer.java index 8ed0087dc60..8615472f777 100644 --- a/jdk/src/share/classes/javax/swing/tree/TreeCellRenderer.java +++ b/jdk/src/share/classes/javax/swing/tree/TreeCellRenderer.java @@ -67,7 +67,14 @@ public interface TreeCellRenderer { * } * * - * @return the Component that the renderer uses to draw the value + * @param tree the receiver is being configured for + * @param value the value to render + * @param selected whether node is selected + * @param expanded whether node is expanded + * @param leaf whether node is a lead node + * @param row row index + * @param hasFocus whether node has focus + * @return the {@code Component} that the renderer uses to draw the value */ Component getTreeCellRendererComponent(JTree tree, Object value, boolean selected, boolean expanded, diff --git a/jdk/src/share/classes/javax/swing/tree/TreeModel.java b/jdk/src/share/classes/javax/swing/tree/TreeModel.java index 94f7d236647..435c9e51444 100644 --- a/jdk/src/share/classes/javax/swing/tree/TreeModel.java +++ b/jdk/src/share/classes/javax/swing/tree/TreeModel.java @@ -79,8 +79,9 @@ public interface TreeModel * is a valid index for parent (that is index >= 0 && * index < getChildCount(parent)). * - * @param parent a node in the tree, obtained from this data source - * @return the child of parent at index index + * @param parent a node in the tree, obtained from this data source + * @param index index of child to be returned + * @return the child of {@code parent} at index {@code index} */ public Object getChild(Object parent, int index); diff --git a/jdk/src/share/classes/javax/swing/tree/TreeNode.java b/jdk/src/share/classes/javax/swing/tree/TreeNode.java index e6dcbab292a..3633a88fb74 100644 --- a/jdk/src/share/classes/javax/swing/tree/TreeNode.java +++ b/jdk/src/share/classes/javax/swing/tree/TreeNode.java @@ -49,17 +49,24 @@ public interface TreeNode /** * Returns the child TreeNode at index * childIndex. + * + * @param childIndex index of child + * @return the child node at given index */ TreeNode getChildAt(int childIndex); /** * Returns the number of children TreeNodes the receiver * contains. + * + * @return the number of children the receiver contains */ int getChildCount(); /** * Returns the parent TreeNode of the receiver. + * + * @return the parent of the receiver */ TreeNode getParent(); @@ -67,21 +74,30 @@ public interface TreeNode * Returns the index of node in the receivers children. * If the receiver does not contain node, -1 will be * returned. + * + * @param node node to be loked for + * @return index of specified node */ int getIndex(TreeNode node); /** * Returns true if the receiver allows children. + * + * @return whether the receiver allows children */ boolean getAllowsChildren(); /** * Returns true if the receiver is a leaf. + * + * @return whether the receiver is a leaf */ boolean isLeaf(); /** * Returns the children of the receiver as an Enumeration. + * + * @return the children of the receiver as an {@code Enumeration} */ Enumeration children(); } diff --git a/jdk/src/share/classes/javax/swing/tree/TreePath.java b/jdk/src/share/classes/javax/swing/tree/TreePath.java index 4ed1dbafd09..1a45bca1c07 100644 --- a/jdk/src/share/classes/javax/swing/tree/TreePath.java +++ b/jdk/src/share/classes/javax/swing/tree/TreePath.java @@ -320,8 +320,10 @@ public class TreePath extends Object implements Serializable { * plus child. child is the last element * of the newly created {@code TreePath}. * - * @param child the path element to add - * @throws NullPointerException if {@code child} is {@code null} + * @param child the path element to add + * @throws NullPointerException if {@code child} is {@code null} + * @return a new path containing all the elements of this path + * plus {@code child} */ public TreePath pathByAddingChild(Object child) { if(child == null) diff --git a/jdk/src/share/classes/javax/swing/tree/TreeSelectionModel.java b/jdk/src/share/classes/javax/swing/tree/TreeSelectionModel.java index 5df7f392f2e..d0c851dc24c 100644 --- a/jdk/src/share/classes/javax/swing/tree/TreeSelectionModel.java +++ b/jdk/src/share/classes/javax/swing/tree/TreeSelectionModel.java @@ -109,6 +109,8 @@ public interface TreeSelectionModel * selected when the mode is changed to SINGLE_TREE_SELECTION, * only one TreePath will remain selected. It is up to the particular * implementation to decide what TreePath remains selected. + * + * @param mode selection mode to be set */ void setSelectionMode(int mode); @@ -117,6 +119,8 @@ public interface TreeSelectionModel * SINGLE_TREE_SELECTION, * CONTIGUOUS_TREE_SELECTION or * DISCONTIGUOUS_TREE_SELECTION. + * + * @return the current selection mode */ int getSelectionMode(); @@ -125,7 +129,7 @@ public interface TreeSelectionModel * the TreeSelectionListeners are notified. If path is * null, this has the same effect as invoking clearSelection. * - * @param path new path to select + * @param path new path to select */ void setSelectionPath(TreePath path); @@ -134,7 +138,7 @@ public interface TreeSelectionModel * the TreeSelectionListeners are notified. If paths is * null, this has the same effect as invoking clearSelection. * - * @param paths new selection + * @param paths new selection */ void setSelectionPaths(TreePath[] paths); @@ -143,7 +147,7 @@ public interface TreeSelectionModel * in the selection the TreeSelectionListeners are notified. This has * no effect if path is null. * - * @param path the new path to add to the current selection + * @param path the new path to add to the current selection */ void addSelectionPath(TreePath path); @@ -153,7 +157,7 @@ public interface TreeSelectionModel * are notified. This has * no effect if paths is null. * - * @param paths the new paths to add to the current selection + * @param paths the new paths to add to the current selection */ void addSelectionPaths(TreePath[] paths); @@ -162,7 +166,7 @@ public interface TreeSelectionModel * The TreeSelectionListeners are notified. This has no effect if * path is null. * - * @param path the path to remove from the selection + * @param path the path to remove from the selection */ void removeSelectionPath(TreePath path); @@ -172,7 +176,7 @@ public interface TreeSelectionModel * are in the selection, the TreeSelectionListeners are notified. * This method has no effect if paths is null. * - * @param paths the path to remove from the selection + * @param paths the path to remove from the selection */ void removeSelectionPaths(TreePath[] paths); @@ -181,28 +185,39 @@ public interface TreeSelectionModel * up to implementors, and may not necessarily be the TreePath with * the smallest integer value as determined from the * RowMapper. + * + * @return the first path in the selection */ TreePath getSelectionPath(); /** * Returns the paths in the selection. This will return null (or an * empty array) if nothing is currently selected. + * + * @return the paths in the selection */ TreePath[] getSelectionPaths(); /** * Returns the number of paths that are selected. + * + * @return the number of paths that are selected */ int getSelectionCount(); /** * Returns true if the path, path, is in the current * selection. + * + * @param path the path to be loked for + * @return whether the {@code path} is in the current selection */ boolean isPathSelected(TreePath path); /** * Returns true if the selection is currently empty. + * + * @return whether the selection is currently empty */ boolean isSelectionEmpty(); @@ -215,12 +230,17 @@ public interface TreeSelectionModel /** * Sets the RowMapper instance. This instance is used to determine * the row for a particular TreePath. + * + * @param newMapper RowMapper to be set */ void setRowMapper(RowMapper newMapper); /** * Returns the RowMapper instance that is able to map a TreePath to a * row. + * + * @return the RowMapper instance that is able to map a TreePath + * to a row */ RowMapper getRowMapper(); @@ -228,6 +248,8 @@ public interface TreeSelectionModel * Returns all of the currently selected rows. This will return * null (or an empty array) if there are no selected TreePaths or * a RowMapper has not been set. + * + * @return all of the currently selected rows */ int[] getSelectionRows(); @@ -235,6 +257,9 @@ public interface TreeSelectionModel * Returns the smallest value obtained from the RowMapper for the * current set of selected TreePaths. If nothing is selected, * or there is no RowMapper, this will return -1. + * + * @return the smallest value obtained from the RowMapper + * for the current set of selected TreePaths */ int getMinSelectionRow(); @@ -242,11 +267,17 @@ public interface TreeSelectionModel * Returns the largest value obtained from the RowMapper for the * current set of selected TreePaths. If nothing is selected, * or there is no RowMapper, this will return -1. + * + * @return the largest value obtained from the RowMapper + * for the current set of selected TreePaths */ int getMaxSelectionRow(); /** * Returns true if the row identified by row is selected. + * + * @param row row to check + * @return whether the row is selected */ boolean isRowSelected(int row); @@ -264,12 +295,16 @@ public interface TreeSelectionModel /** * Returns the lead selection index. That is the last index that was * added. + * + * @return the lead selection index */ int getLeadSelectionRow(); /** * Returns the last path that was added. This may differ from the * leadSelectionPath property maintained by the JTree. + * + * @return the last path that was added */ TreePath getLeadSelectionPath(); @@ -280,7 +315,7 @@ public interface TreeSelectionModel * A PropertyChangeEvent will get fired when the selection mode * changes. * - * @param listener the PropertyChangeListener to be added + * @param listener the PropertyChangeListener to be added */ void addPropertyChangeListener(PropertyChangeListener listener); @@ -289,7 +324,7 @@ public interface TreeSelectionModel * This removes a PropertyChangeListener that was registered * for all properties. * - * @param listener the PropertyChangeListener to be removed + * @param listener the PropertyChangeListener to be removed */ void removePropertyChangeListener(PropertyChangeListener listener); @@ -297,7 +332,7 @@ public interface TreeSelectionModel * Adds x to the list of listeners that are notified each time the * set of selected TreePaths changes. * - * @param x the new listener to be added + * @param x the new listener to be added */ void addTreeSelectionListener(TreeSelectionListener x); @@ -305,7 +340,7 @@ public interface TreeSelectionModel * Removes x from the list of listeners that are notified each time * the set of selected TreePaths changes. * - * @param x the listener to remove + * @param x the listener to remove */ void removeTreeSelectionListener(TreeSelectionListener x); } diff --git a/jdk/src/share/classes/javax/swing/undo/CompoundEdit.java b/jdk/src/share/classes/javax/swing/undo/CompoundEdit.java index 5e95f4130e4..4963262d0ac 100644 --- a/jdk/src/share/classes/javax/swing/undo/CompoundEdit.java +++ b/jdk/src/share/classes/javax/swing/undo/CompoundEdit.java @@ -82,6 +82,9 @@ public class CompoundEdit extends AbstractUndoableEdit { * Returns the last UndoableEdit in * edits, or null * if edits is empty. + * + * @return the last {@code UndoableEdit} in {@code edits}, + * or {@code null} if {@code edits} is empty. */ protected UndoableEdit lastEdit() { int count = edits.size(); @@ -182,6 +185,7 @@ public class CompoundEdit extends AbstractUndoableEdit { * received end. This generally means that edits are still being * added to it. * + * @return whether this edit is in progress * @see #end */ public boolean isInProgress() { diff --git a/jdk/src/share/classes/javax/swing/undo/StateEditable.java b/jdk/src/share/classes/javax/swing/undo/StateEditable.java index 492a2f91470..d8de2cf4871 100644 --- a/jdk/src/share/classes/javax/swing/undo/StateEditable.java +++ b/jdk/src/share/classes/javax/swing/undo/StateEditable.java @@ -43,12 +43,16 @@ public interface StateEditable { /** * Upon receiving this message the receiver should place any relevant * state into state. + * + * @param state Hashtable object to store the state */ public void storeState(Hashtable state); /** * Upon receiving this message the receiver should extract any relevant * state out of state. + * + * @param state Hashtable object to restore the state from it */ public void restoreState(Hashtable state); } // End of interface StateEditable diff --git a/jdk/src/share/classes/javax/swing/undo/UndoManager.java b/jdk/src/share/classes/javax/swing/undo/UndoManager.java index a95ebf25ce8..8f141e1d932 100644 --- a/jdk/src/share/classes/javax/swing/undo/UndoManager.java +++ b/jdk/src/share/classes/javax/swing/undo/UndoManager.java @@ -326,6 +326,7 @@ public class UndoManager extends CompoundEdit implements UndoableEditListener { * Undoes all changes from the index of the next edit to * edit, updating the index of the next edit appropriately. * + * @param edit the edit to be undo to * @throws CannotUndoException if one of the edits throws * CannotUndoException */ @@ -342,6 +343,7 @@ public class UndoManager extends CompoundEdit implements UndoableEditListener { * Redoes all changes from the index of the next edit to * edit, updating the index of the next edit appropriately. * + * @param edit the edit to be redo to * @throws CannotRedoException if one of the edits throws * CannotRedoException */ diff --git a/jdk/src/share/classes/javax/swing/undo/UndoableEditSupport.java b/jdk/src/share/classes/javax/swing/undo/UndoableEditSupport.java index a1927f34a32..21c2b61cb77 100644 --- a/jdk/src/share/classes/javax/swing/undo/UndoableEditSupport.java +++ b/jdk/src/share/classes/javax/swing/undo/UndoableEditSupport.java @@ -96,6 +96,8 @@ public class UndoableEditSupport { * Called only from postEdit and endUpdate. Calls * undoableEditHappened in all listeners. No synchronization * is performed here, since the two calling methods are synchronized. + * + * @param e edit to be verified */ protected void _postEdit(UndoableEdit e) { UndoableEditEvent ev = new UndoableEditEvent(realSource, e); @@ -110,6 +112,8 @@ public class UndoableEditSupport { * DEADLOCK WARNING: Calling this method may call * undoableEditHappened in all listeners. * It is unwise to call this method from one of its listeners. + * + * @param e edit to be posted */ public synchronized void postEdit(UndoableEdit e) { if (updateLevel == 0) { @@ -142,6 +146,8 @@ public class UndoableEditSupport { /** * Called only from beginUpdate. * Exposed here for subclasses' use. + * + * @return new created {@code CompoundEdit} object */ protected CompoundEdit createCompoundEdit() { return new CompoundEdit();