7020860: BasicTreeUI contains getters/setters with unclear spec

Reviewed-by: jdv, prr, serb

src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTreeUI.java

@@ -403,9 +403,12 @@ public Icon getCollapsedIcon() {
     //
 
     /**
-     * Updates the componentListener, if necessary.
+     * Sets the {@code largeModel}.
      *
-     * @param largeModel the new value
+     * Called when the {@code largeModel} property is changed in the drawn tree
+     * component.
+     *
+     * @param largeModel the new value of the {@code largeModel} property
      */
     protected void setLargeModel(boolean largeModel) {
         if(getRowHeight() < 1)
@@ -432,7 +435,10 @@ protected boolean isLargeModel() {
     /**
      * Sets the row height, this is forwarded to the treeState.
      *
-     * @param rowHeight the row height
+     * Called when the {@code rowHeight} property is changed in
+     * the drawn tree component.
+     *
+     * @param rowHeight the new value of the {@code rowHeight} property
      */
     protected void setRowHeight(int rowHeight) {
         completeEditing();
@@ -444,9 +450,11 @@ protected void setRowHeight(int rowHeight) {
     }
 
     /**
-     * Returns the row height.
+     * Returns the height of each row in the drawn tree component. If the
+     * returned value is less than or equal to 0 the height for each row is
+     * determined by the renderer.
      *
-     * @return the row height
+     * @return the height of each row, in pixels
      */
     protected int getRowHeight() {
         return (tree == null) ? -1 : tree.getRowHeight();
@@ -456,7 +464,10 @@ protected int getRowHeight() {
      * Sets the {@code TreeCellRenderer} to {@code tcr}. This invokes
      * {@code updateRenderer}.
      *
-     * @param tcr the new value
+     * Called when the {@code cellRenderer} property is changed in
+     * the drawn tree component.
+     *
+     * @param tcr the new value of the {@code cellRenderer} property
      */
     protected void setCellRenderer(TreeCellRenderer tcr) {
         completeEditing();
@@ -468,10 +479,10 @@ protected void setCellRenderer(TreeCellRenderer tcr) {
     }
 
     /**
-     * Return {@code currentCellRenderer}, which will either be the trees
-     * renderer, or {@code defaultCellRenderer}, which ever wasn't null.
+     * Returns the current instance of the {@link TreeCellRenderer} that is
+     * rendering each cell.
      *
-     * @return an instance of {@code TreeCellRenderer}
+     * @return the {@link TreeCellRenderer} instance
      */
     protected TreeCellRenderer getCellRenderer() {
         return currentCellRenderer;
@@ -510,7 +521,10 @@ protected TreeModel getModel() {
     /**
      * Sets the root to being visible.
      *
-     * @param newValue the new value
+     * Called when the {@code rootVisible} property is changed in the drawn tree
+     * component.
+     *
+     * @param newValue the new value of the {@code rootVisible} property
      */
     protected void setRootVisible(boolean newValue) {
         completeEditing();
@@ -523,9 +537,9 @@ protected void setRootVisible(boolean newValue) {
     }
 
     /**
-     * Returns {@code true} if the tree root is visible.
+     * Returns whether the root node of the drawn tree component should be displayed.
      *
-     * @return {@code true} if the tree root is visible
+     * @return {@code true} if the root node of the tree is displayed
      */
     protected boolean isRootVisible() {
         return (tree != null) ? tree.isRootVisible() : false;
@@ -534,7 +548,10 @@ protected boolean isRootVisible() {
     /**
      * Determines whether the node handles are to be displayed.
      *
-     * @param newValue the new value
+     * Called when the {@code showsRootHandles} property is changed in the drawn
+     * tree component.
+     *
+     * @param newValue the new value of the {@code showsRootHandles} property
      */
     protected void setShowsRootHandles(boolean newValue) {
         completeEditing();
@@ -557,16 +574,20 @@ protected boolean getShowsRootHandles() {
     /**
      * Sets the cell editor.
      *
-     * @param editor the new cell editor
+     * Called when the {@code cellEditor} property is changed in the drawn tree
+     * component.
+     *
+     * @param editor the new value of the {@code cellEditor} property
      */
     protected void setCellEditor(TreeCellEditor editor) {
         updateCellEditor();
     }
 
     /**
-     * Returns an instance of {@code TreeCellEditor}.
+     * Returns the editor used to edit entries in the drawn tree component, or
+     * {@code null} if the tree cannot be edited.
      *
-     * @return an instance of {@code TreeCellEditor}
+     * @return the {@link TreeCellEditor} instance, or {@code null}
      */
     protected TreeCellEditor getCellEditor() {
         return (tree != null) ? tree.getCellEditor() : null;
@@ -575,14 +596,17 @@ protected TreeCellEditor getCellEditor() {
     /**
      * Configures the receiver to allow, or not allow, editing.
      *
-     * @param newValue the new value
+     * Called when the {@code editable} property is changed in the drawn tree
+     * component.
+     *
+     * @param newValue the new value of the {@code editable} property
      */
     protected void setEditable(boolean newValue) {
         updateCellEditor();
     }
 
     /**
-     * Returns {@code true} if the tree is editable.
+     * Returns whether the drawn tree component should be enabled for editing.
      *
      * @return {@code true} if the tree is editable
      */
@@ -594,7 +618,10 @@ protected boolean isEditable() {
      * Resets the selection model. The appropriate listener are installed
      * on the model.
      *
-     * @param newLSM new selection model
+     * Called when the {@code selectionModel} property is changed in the drawn tree
+     * component.
+     *
+     * @param newLSM the new value of the {@code selectionModel} property
      */
     protected void setSelectionModel(TreeSelectionModel newLSM) {
         completeEditing();
@@ -623,9 +650,10 @@ else if(treeState != null)
     }
 
     /**
-     * Returns the tree selection model.
+     * Returns the current instance of the {@link TreeSelectionModel} which is
+     * the model for selections.
      *
-     * @return the tree selection model
+     * @return the {@link TreeSelectionModel} instance
      */
     protected TreeSelectionModel getSelectionModel() {
         return treeSelectionModel;