[cp-patches] FYI: Fixed API docs for javax.swing interfaces

[Roman Kennke]

I had a quick look at the API documentation of Swing at 
http://developer.classpath.org/doc/ and found that it is in a really bad 
shape. In the light of the upcoming 0.17 release I did a quick polish up 
for that, so that it does not look that ugly. I have started with the 
class descriptions of all javax.swing interfaces.

2005-07-13  Roman Kennke  <address@hidden>

        * javax/swing/BoundedRangeModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/ButtonModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/CellEditor.java:
        Added/Fixed interface API documentation.
        * javax/swing/ComboBoxEditor.java:
        Added/Fixed interface API documentation.
        * javax/swing/ComboBoxModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/Icon.java:
        Added/Fixed interface API documentation.
        * javax/swing/JComboBox.java
        (KeySelectionManager): Added/Fixed interface API documentation.
        * javax/swing/ListCellRenderer.java:
        Added/Fixed interface API documentation.
        * javax/swing/ListModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/ListSelectionModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/MenuElement.java:
        Added/Fixed interface API documentation.
        * javax/swing/MutableComboBoxModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/Renderer.java:
        Added/Fixed interface API documentation.
        * javax/swing/RootPaneContainer.java:
        Added/Fixed interface API documentation.
        * javax/swing/ScrollPaneConstants.java:
        Added/Fixed interface API documentation.
        * javax/swing/Scrollable.java:
        Added/Fixed interface API documentation.
        * javax/swing/SingleSelectionModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/SpinnerModel.java:
        Added/Fixed interface API documentation.
        * javax/swing/SwingConstants.java:
        Added/Fixed interface API documentation.
        * javax/swing/UIDefaults.java
        (ActiveValue): interface API documentation.
        (LazyValue): interface API documentation.
        * javax/swing/WindowConstants.java:
        Added/Fixed interface API documentation.
        * javax/swing/package.html: Fixed package description to be more
        a little bit more concise.

/Roman

Index: javax/swing/BoundedRangeModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/BoundedRangeModel.java,v
retrieving revision 1.6
diff -u -r1.6 BoundedRangeModel.java
--- javax/swing/BoundedRangeModel.java  2 Jul 2005 20:32:46 -0000       1.6
+++ javax/swing/BoundedRangeModel.java  13 Jul 2005 21:20:59 -0000
@@ -41,6 +41,9 @@
 import javax.swing.event.ChangeListener;
 
 /**
+ * The data model that is used in components that display a range of values,
+ * like address@hidden JProgressBar} and address@hidden JSlider}.
+ *
  * @author Andrew Selkirk
  */
 public interface BoundedRangeModel
Index: javax/swing/ButtonModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ButtonModel.java,v
retrieving revision 1.6
diff -u -r1.6 ButtonModel.java
--- javax/swing/ButtonModel.java        2 Jul 2005 20:32:46 -0000       1.6
+++ javax/swing/ButtonModel.java        13 Jul 2005 21:20:59 -0000
@@ -44,6 +44,9 @@
 
 import javax.swing.event.ChangeListener;
 
+/**
+ * The data model that is used in all kinds of buttons.
+ */
 public interface ButtonModel extends ItemSelectable
 {  
     boolean isArmed();     
Index: javax/swing/CellEditor.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/CellEditor.java,v
retrieving revision 1.8
diff -u -r1.8 CellEditor.java
--- javax/swing/CellEditor.java 2 Jul 2005 20:32:46 -0000       1.8
+++ javax/swing/CellEditor.java 13 Jul 2005 21:20:59 -0000
@@ -43,9 +43,10 @@
 import javax.swing.event.CellEditorListener;
 
 /**
- * CellEditor
- * @author     Andrew Selkirk
- * @version    1.0
+ * Provides edit capabilities for components that display cells like
+ * address@hidden JTable}, address@hidden JList} and address@hidden JTree}.
+ *
+ * @author Andrew Selkirk
  */
 public interface CellEditor
 {
Index: javax/swing/ComboBoxEditor.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ComboBoxEditor.java,v
retrieving revision 1.5
diff -u -r1.5 ComboBoxEditor.java
--- javax/swing/ComboBoxEditor.java     2 Jul 2005 20:32:46 -0000       1.5
+++ javax/swing/ComboBoxEditor.java     13 Jul 2005 21:20:59 -0000
@@ -41,11 +41,10 @@
 import java.awt.event.ActionListener;
 
 /**
- * ComboBoxEditor
+ * Provides edit capabilities for address@hidden JComboBox}es.
  *
  * @author Andrew Selkirk
  * @author Olga Rodimina
- * @version 1.0
  */
 public interface ComboBoxEditor
 {
Index: javax/swing/ComboBoxModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ComboBoxModel.java,v
retrieving revision 1.4
diff -u -r1.4 ComboBoxModel.java
--- javax/swing/ComboBoxModel.java      2 Jul 2005 20:32:46 -0000       1.4
+++ javax/swing/ComboBoxModel.java      13 Jul 2005 21:20:59 -0000
@@ -39,13 +39,12 @@
 
 
 /**
- * ComboBoxModel is a data model for JComboBox. This model keeps
+ * The data model for address@hidden JComboBox}. This model keeps
  * track of elements contained in the JComboBox as well as the current
  * combo box selection. Whenever selection in the JComboBox changes, the
  * ComboBoxModel should fire ListDataEvents to ComboBox's ListDataListeners.
  *
- * @author        Andrew Selkirk
- * @version        1.0
+ * @author Andrew Selkirk
  */
 public interface ComboBoxModel extends ListModel
 {
Index: javax/swing/Icon.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/Icon.java,v
retrieving revision 1.5
diff -u -r1.5 Icon.java
--- javax/swing/Icon.java       2 Jul 2005 20:32:47 -0000       1.5
+++ javax/swing/Icon.java       13 Jul 2005 21:20:59 -0000
@@ -40,6 +40,10 @@
 import java.awt.Component;
 import java.awt.Graphics;
 
+/**
+ * Defines the methods that an object must implement if it should be used
+ * as an icon in Swing.
+ */
 public interface Icon
 {
   int getIconHeight();
Index: javax/swing/JComboBox.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/JComboBox.java,v
retrieving revision 1.16
diff -u -r1.16 JComboBox.java
--- javax/swing/JComboBox.java  2 Jul 2005 20:32:47 -0000       1.16
+++ javax/swing/JComboBox.java  13 Jul 2005 21:20:59 -0000
@@ -79,7 +79,7 @@
   private static final long serialVersionUID = 5654585963292734470L;
 
   /**
-   * KeySelectionManager interface. Class implementing this interface are
+   * Classes implementing this interface are
    * responsible for matching key characters typed by the user with combo
    * box's items.
    */
Index: javax/swing/ListCellRenderer.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ListCellRenderer.java,v
retrieving revision 1.5
diff -u -r1.5 ListCellRenderer.java
--- javax/swing/ListCellRenderer.java   2 Jul 2005 20:32:49 -0000       1.5
+++ javax/swing/ListCellRenderer.java   13 Jul 2005 21:21:00 -0000
@@ -39,6 +39,9 @@
 
 import java.awt.Component;
 
+/**
+ * Renders the cells of a address@hidden JList}.
+ */
 public interface ListCellRenderer
 {
     Component getListCellRendererComponent(JList list,
Index: javax/swing/ListModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ListModel.java,v
retrieving revision 1.7
diff -u -r1.7 ListModel.java
--- javax/swing/ListModel.java  2 Jul 2005 20:32:49 -0000       1.7
+++ javax/swing/ListModel.java  13 Jul 2005 21:21:00 -0000
@@ -40,8 +40,7 @@
 import javax.swing.event.ListDataListener;
 
 /**
- * This is an interface to general list-like data, typically used as the
- * model object of a address@hidden JList} component.
+ * The data model that is typically used in address@hidden JList}.
  *
  * @author Graydon Hoare (address@hidden)
  */
Index: javax/swing/ListSelectionModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ListSelectionModel.java,v
retrieving revision 1.6
diff -u -r1.6 ListSelectionModel.java
--- javax/swing/ListSelectionModel.java 2 Jul 2005 20:32:49 -0000       1.6
+++ javax/swing/ListSelectionModel.java 13 Jul 2005 21:21:00 -0000
@@ -40,6 +40,10 @@
 
 import javax.swing.event.ListSelectionListener;
 
+/**
+ * The model that is used in address@hidden JList} to define the 
selected/not-selected
+ * cells of that list.
+ */
 public interface ListSelectionModel
 {
   int SINGLE_SELECTION = 0;
Index: javax/swing/MenuElement.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/MenuElement.java,v
retrieving revision 1.6
diff -u -r1.6 MenuElement.java
--- javax/swing/MenuElement.java        2 Jul 2005 20:32:49 -0000       1.6
+++ javax/swing/MenuElement.java        13 Jul 2005 21:21:00 -0000
@@ -42,9 +42,10 @@
 import java.awt.event.MouseEvent;
 
 /**
- * MenuElement
- * @author     Andrew Selkirk
- * @version    1.0
+ * Defines the methods that any menu element in a address@hidden JMenu} must
+ * implement.
+ *
+ * @author Andrew Selkirk
  */
 public interface MenuElement {
 
Index: javax/swing/MutableComboBoxModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/MutableComboBoxModel.java,v
retrieving revision 1.4
diff -u -r1.4 MutableComboBoxModel.java
--- javax/swing/MutableComboBoxModel.java       2 Jul 2005 20:32:49 -0000       
1.4
+++ javax/swing/MutableComboBoxModel.java       13 Jul 2005 21:21:00 -0000
@@ -38,14 +38,13 @@
 package javax.swing;
 
 /**
- * MutableComboBoxModel is interface for data model that keeps track of the
+ * A data model used in address@hidden JComboBox}es that keeps track of the
  * components data and provides methods to insert and remove elements from
- * it. The Classes implementing this interface should  fire appropriate
- * events indicating the undergoing change in the data model.
+ * it. The classes implementing this interface should
+ * fire appropriate events indicating the undergoing change in the data model.
  *
  * @author Andrew Selkirk
  * @author Olga Rodimina
- * @version 1.0
  */
 public interface MutableComboBoxModel extends ComboBoxModel
 {
Index: javax/swing/Renderer.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/Renderer.java,v
retrieving revision 1.4
diff -u -r1.4 Renderer.java
--- javax/swing/Renderer.java   2 Jul 2005 20:32:49 -0000       1.4
+++ javax/swing/Renderer.java   13 Jul 2005 21:21:00 -0000
@@ -40,9 +40,14 @@
 import java.awt.Component;
 
 /**
- * Renderer
- * @author     Andrew Selkirk
- * @version    1.0
+ * This interface is not used and exists only for compatibility.
+ * It probably has been replaced by address@hidden ListCellRenderer}, 
address@hidden
+ * javax.swing.table.TableCellRenderer} and address@hidden
+ * javax.swing.tree.TreeCellRenderer}.
+ *
+ * @specnote This interface is not used and exists only for compatibility.
+ *           
+ * @author Andrew Selkirk
  */
 public interface Renderer {
 
Index: javax/swing/RootPaneContainer.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/RootPaneContainer.java,v
retrieving revision 1.5
diff -u -r1.5 RootPaneContainer.java
--- javax/swing/RootPaneContainer.java  2 Jul 2005 20:32:49 -0000       1.5
+++ javax/swing/RootPaneContainer.java  13 Jul 2005 21:21:00 -0000
@@ -42,9 +42,11 @@
 import java.awt.Container;
 
 /**
- * RootPaneContainer
- * @author     Andrew Selkirk
- * @version    1.0
+ * Components that contain a single address@hidden JRootPane} as only child
+ * implement this interface, typically this is implemented by the
+ * Swing top-level containers.
+ *
+ * @author Andrew Selkirk
  */
 public interface RootPaneContainer {
 
Index: javax/swing/ScrollPaneConstants.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ScrollPaneConstants.java,v
retrieving revision 1.4
diff -u -r1.4 ScrollPaneConstants.java
--- javax/swing/ScrollPaneConstants.java        2 Jul 2005 20:32:49 -0000       
1.4
+++ javax/swing/ScrollPaneConstants.java        13 Jul 2005 21:21:00 -0000
@@ -38,9 +38,10 @@
 package javax.swing;
 
 /**
- * ScrollPaneConstants
- * @author     Andrew Selkirk
- * @version    1.0
+ * Defines some constants that are used in address@hidden JScrollPane} and 
related
+ * components.
+ *
+ * @author Andrew Selkirk
  */
 public interface ScrollPaneConstants
 {
Index: javax/swing/Scrollable.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/Scrollable.java,v
retrieving revision 1.4
diff -u -r1.4 Scrollable.java
--- javax/swing/Scrollable.java 2 Jul 2005 20:32:49 -0000       1.4
+++ javax/swing/Scrollable.java 13 Jul 2005 21:21:00 -0000
@@ -40,6 +40,12 @@
 import java.awt.Dimension;
 import java.awt.Rectangle;
 
+/**
+ * Defines the method that a component should implement to behave nicely
+ * in address@hidden JScrollPane}s. Note that this is not required for a 
component
+ * to be used in a <code>JScrollPane</code>, but can highly improve the
+ * user experience when scrolling the component.
+ */
 public interface Scrollable
 {
     Dimension getPreferredScrollableViewportSize();
Index: javax/swing/SingleSelectionModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/SingleSelectionModel.java,v
retrieving revision 1.4
diff -u -r1.4 SingleSelectionModel.java
--- javax/swing/SingleSelectionModel.java       2 Jul 2005 20:32:49 -0000       
1.4
+++ javax/swing/SingleSelectionModel.java       13 Jul 2005 21:21:00 -0000
@@ -40,9 +40,11 @@
 import javax.swing.event.ChangeListener;
 
 /**
- * SingleSelectionModel
- * @author     Andrew Selkirk
- * @version    1.0
+ * A data model that is used in components that support at most one
+ * selected element, like address@hidden JTabbedPane}, address@hidden JMenu} 
and
+ * address@hidden JPopupMenu}.
+ *
+ * @author Andrew Selkirk
  */
 public interface SingleSelectionModel {
 
Index: javax/swing/SpinnerModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/SpinnerModel.java,v
retrieving revision 1.5
diff -u -r1.5 SpinnerModel.java
--- javax/swing/SpinnerModel.java       2 Jul 2005 20:32:49 -0000       1.5
+++ javax/swing/SpinnerModel.java       13 Jul 2005 21:21:00 -0000
@@ -41,6 +41,8 @@
 import javax.swing.event.ChangeListener;
 
 /**
+ * The data model that is used in address@hidden JSpinner}s.
+ *
  * @since 1.4
  */
 public interface SpinnerModel
Index: javax/swing/SwingConstants.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/SwingConstants.java,v
retrieving revision 1.6
diff -u -r1.6 SwingConstants.java
--- javax/swing/SwingConstants.java     2 Jul 2005 20:32:49 -0000       1.6
+++ javax/swing/SwingConstants.java     13 Jul 2005 21:21:00 -0000
@@ -38,6 +38,9 @@
 
 package javax.swing;
 
+/**
+ * Defines constant values that are used throughout the Swing packages.
+ */
 public interface SwingConstants
 {
   int CENTER       = 0;
Index: javax/swing/UIDefaults.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/UIDefaults.java,v
retrieving revision 1.20
diff -u -r1.20 UIDefaults.java
--- javax/swing/UIDefaults.java 2 Jul 2005 20:32:49 -0000       1.20
+++ javax/swing/UIDefaults.java 13 Jul 2005 21:21:00 -0000
@@ -74,6 +74,13 @@
   /** We use this for firing PropertyChangeEvents. */
   private PropertyChangeSupport propertyChangeSupport;
 
+  /**
+   * Used for lazy instantiation of UIDefaults values so that they are not
+   * all loaded when a Swing application starts up, but only the values that
+   * are really needed. An <code>ActiveValue</code> is newly instantiated
+   * every time when the value is requested, as opposed to the normal
+   * address@hidden LazyValue} that is only instantiated once.
+   */
   public static interface ActiveValue
   {
     Object createValue(UIDefaults table);
@@ -98,6 +105,13 @@
     }
   }
 
+  /**
+   * Used for lazy instantiation of UIDefaults values so that they are not
+   * all loaded when a Swing application starts up, but only the values that
+   * are really needed. A <code>LazyValue</code> is only instantiated once,
+   * as opposed to the address@hidden ActiveValue} that is newly created every 
time
+   * it is requested.
+   */
   public static interface LazyValue
   {
     Object createValue(UIDefaults table);
Index: javax/swing/WindowConstants.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/WindowConstants.java,v
retrieving revision 1.4
diff -u -r1.4 WindowConstants.java
--- javax/swing/WindowConstants.java    2 Jul 2005 20:32:49 -0000       1.4
+++ javax/swing/WindowConstants.java    13 Jul 2005 21:21:00 -0000
@@ -38,9 +38,10 @@
 package javax.swing;
 
 /**
- * WindowConstants
- * @author     Andrew Selkirk
- * @version    1.0
+ * Defines some constants that are used in Swing's top-level
+ * containers.
+ *
+ * @author Andrew Selkirk
  */
 public interface WindowConstants {
 
Index: javax/swing/package.html
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/package.html,v
retrieving revision 1.3
diff -u -r1.3 package.html
--- javax/swing/package.html    2 Jul 2005 20:32:49 -0000       1.3
+++ javax/swing/package.html    13 Jul 2005 21:21:00 -0000
@@ -40,7 +40,7 @@
 <head><title>GNU Classpath - javax.swing</title></head>
 
 <body>
-<p>A base package providing a collection of cross-platform user interface
+<p>Provides a collection of cross-platform user interface
 components.</p>
 
 </body>