[cp-patches] FYI: API fixes for Swing

[Roman Kennke]

Hi added and fixed some API comments for Swing.

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

        * javax/swing/AbstractAction.java
        Fixed / Added API doc comments for the class description.
        * javax/swing/AbstractButton.java: Likewise.
        * javax/swing/AbstractCellEditor.java: Likewise.
        * javax/swing/AbstractListModel.java: Likewise.
        * javax/swing/AbstractSpinnerModel.java: Likewise.
        * javax/swing/ActionMap.java: Likewise.
        * javax/swing/BorderFactory.java: Likewise.
        * javax/swing/Box.java: Likewise.
        * javax/swing/BoxLayout.java: Likewise.
        * javax/swing/ButtonGroup.java: Likewise.
        * javax/swing/CellRendererPane.java: Likewise.
        * javax/swing/ComponentInputMap.java: Likewise.
        * javax/swing/DebugGraphics.java: Likewise.

/Roman

? javax/swing/DumpHierarchy.java
Index: javax/swing/AbstractAction.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractAction.java,v
retrieving revision 1.15
diff -u -r1.15 AbstractAction.java
--- javax/swing/AbstractAction.java     5 Jul 2005 14:57:21 -0000       1.15
+++ javax/swing/AbstractAction.java     26 Jul 2005 15:29:36 -0000
@@ -50,8 +50,7 @@
 /**
  * A base class for implementing the address@hidden Action} interface.
  * 
- * @author     Andrew Selkirk
- * @version    1.0
+ * @author Andrew Selkirk
  */
 public abstract class AbstractAction
   implements Action, Cloneable, Serializable
Index: javax/swing/AbstractButton.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractButton.java,v
retrieving revision 1.41
diff -u -r1.41 AbstractButton.java
--- javax/swing/AbstractButton.java     21 Jul 2005 12:07:06 -0000      1.41
+++ javax/swing/AbstractButton.java     26 Jul 2005 15:29:36 -0000
@@ -65,18 +65,13 @@
 
 
 /**
- * <p>The purpose of this class is to serve as a facade over a number of
- * classes which collectively represent the semantics of a button: the
- * button's model, its listeners, its action, and its look and feel. Some
- * parts of a button's state are stored explicitly in this class, other
- * parts are delegates to the model. Some methods related to buttons are
- * implemented in this class, other methods pass through to the current 
- * model or look and feel.</p>
+ * Provides an abstract implementation of common button behaviour,
+ * data model and look &amp; feel.
  *
- * <p>Furthermore this class is supposed to serve as a base class for
+ * <p>This class is supposed to serve as a base class for
  * several kinds of buttons with similar but non-identical semantics:
- * toggle buttons (radio buttons and checkboxes), simple "push" buttons,
- * menu items.</p>
+ * toggle buttons (radio buttons and checkboxes), simple push buttons,
+ * menu items, etc.</p>
  *
  * <p>Buttons have many properties, some of which are stored in this class
  * while others are delegated to the button's model. The following properties
Index: javax/swing/AbstractCellEditor.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractCellEditor.java,v
retrieving revision 1.12
diff -u -r1.12 AbstractCellEditor.java
--- javax/swing/AbstractCellEditor.java 2 Jul 2005 20:32:46 -0000       1.12
+++ javax/swing/AbstractCellEditor.java 26 Jul 2005 15:29:36 -0000
@@ -46,11 +46,10 @@
 import javax.swing.event.EventListenerList;
 
 /**
- * The abstract superclass for table and tree cells. This provides some
+ * An abstract superclass for table and tree cell editors. This provides some
  * common shared functionality.
  *
- * @author     Andrew Selkirk
- * @version    1.0
+ * @author Andrew Selkirk
  */
 public abstract class AbstractCellEditor
   implements CellEditor, Serializable
Index: javax/swing/AbstractListModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractListModel.java,v
retrieving revision 1.12
diff -u -r1.12 AbstractListModel.java
--- javax/swing/AbstractListModel.java  21 Jul 2005 14:59:30 -0000      1.12
+++ javax/swing/AbstractListModel.java  26 Jul 2005 15:29:36 -0000
@@ -46,11 +46,10 @@
 import javax.swing.event.ListDataListener;
 
 /**
- * AbstractListModel
+ * Provides standard implementations of some methods in address@hidden 
ListModel}.
  *
  * @author Ronald Veldema
  * @author Andrew Selkirk
- * @version 1.0
  */
 public abstract class AbstractListModel implements ListModel, Serializable
 {
Index: javax/swing/AbstractSpinnerModel.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractSpinnerModel.java,v
retrieving revision 1.3
diff -u -r1.3 AbstractSpinnerModel.java
--- javax/swing/AbstractSpinnerModel.java       2 Jul 2005 20:32:46 -0000       
1.3
+++ javax/swing/AbstractSpinnerModel.java       26 Jul 2005 15:29:36 -0000
@@ -45,9 +45,10 @@
 import javax.swing.event.EventListenerList;
 
 /**
- * AbstractSpinnerModel
- * @author     Ka-Hing Cheung
- * @version    1.0
+ * Provides standard implementations for some of the methods in
+ * address@hidden SpinnerModel}.
+ *
+ * @author Ka-Hing Cheung
  */
 public abstract class AbstractSpinnerModel implements SpinnerModel
 {
Index: javax/swing/ActionMap.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ActionMap.java,v
retrieving revision 1.10
diff -u -r1.10 ActionMap.java
--- javax/swing/ActionMap.java  2 Jul 2005 20:32:46 -0000       1.10
+++ javax/swing/ActionMap.java  26 Jul 2005 15:29:36 -0000
@@ -49,6 +49,14 @@
 
 
 /**
+ * Maps arbitrary keys (usually Strings) to address@hidden Action} instances. 
This
+ * is used in combination with address@hidden InputMap}s.
+ *
+ * If a component receives an input event, this is looked up in
+ * the component's <code>InputMap</code>. The result is an object which
+ * serves as a key to the components <code>ActionMap</code>. Finally
+ * the <code>Action</code> that is stored is executed.
+ *
  * @author Andrew Selkirk
  * @author Michael Koch
  */
Index: javax/swing/BorderFactory.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/BorderFactory.java,v
retrieving revision 1.11
diff -u -r1.11 BorderFactory.java
--- javax/swing/BorderFactory.java      21 Jul 2005 14:59:31 -0000      1.11
+++ javax/swing/BorderFactory.java      26 Jul 2005 15:29:36 -0000
@@ -50,6 +50,11 @@
 import javax.swing.border.MatteBorder;
 import javax.swing.border.TitledBorder;
 
+/**
+ * A factory for commonly used borders.
+ *
+ * @author original author unknown
+ */
 public class BorderFactory
 {
   private BorderFactory()
Index: javax/swing/Box.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/Box.java,v
retrieving revision 1.15
diff -u -r1.15 Box.java
--- javax/swing/Box.java        2 Jul 2005 20:32:46 -0000       1.15
+++ javax/swing/Box.java        26 Jul 2005 15:29:36 -0000
@@ -60,6 +60,9 @@
 {
   private static final long serialVersionUID = 1525417495883046342L;
   
+  /**
+   * Provides accessibility support for <code>Box</code>es.
+   */
   // FIXME: disable to make libjava compile; visibility rules are broken
   protected class AccessibleBox // extends Container.AccessibleAWTContainer
   {
@@ -82,6 +85,9 @@
   {
     private static final long serialVersionUID = -1204263191910183998L;
   
+    /**
+     * Provides accessibility support for <code>Box.Filler</code>.
+     */
     // FIXME: disable to make libjava compile; visibility rules are broken
     protected class AccessibleBoxFiller // extends 
Component.AccessibleAWTComponent
     {
Index: javax/swing/BoxLayout.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/BoxLayout.java,v
retrieving revision 1.16
diff -u -r1.16 BoxLayout.java
--- javax/swing/BoxLayout.java  21 Jul 2005 14:59:31 -0000      1.16
+++ javax/swing/BoxLayout.java  26 Jul 2005 15:29:36 -0000
@@ -53,7 +53,8 @@
 import gnu.java.awt.AWTUtilities;
 
 /**
- * A layout for swing components.
+ * A layout that stacks the children of a container in a Box, either
+ * horizontally or vertically.
  *
  * @author Ronald Veldema (address@hidden)
  * @author Roman Kennke (address@hidden)
Index: javax/swing/ButtonGroup.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ButtonGroup.java,v
retrieving revision 1.9
diff -u -r1.9 ButtonGroup.java
--- javax/swing/ButtonGroup.java        2 Jul 2005 20:32:46 -0000       1.9
+++ javax/swing/ButtonGroup.java        26 Jul 2005 15:29:36 -0000
@@ -43,7 +43,25 @@
 
 
 /**
- * DOCUMENT ME!
+ * Logically groups a set of buttons, so that only one of the buttons in
+ * a <code>ButtonGroup</code> can be selected at the same time. If one
+ * button in a <code>ButtonGroup</code> is selected, all other buttons
+ * are automatically deselected.
+ *
+ * While <code>ButtonGroup</code> can be used for all buttons that are derived
+ * from address@hidden AbstractButton}, it is normally only used for
+ * address@hidden JRadioButton}s, address@hidden JRadioButtonMenuItem}s and
+ * address@hidden JToggleButton}s.
+ *
+ * You could use it for address@hidden JCheckBox}es, but for the sake of 
usability
+ * this is strongly discouraged because the common expectation of checkboxes
+ * is that the user is allowed to make multiple selections.
+ *
+ * It makes no sense to put address@hidden JButton}s or address@hidden 
JMenuItem}s in
+ * a <code>ButtonGroup</code> because they don't implement the
+ * <code>selected</code> semantics.
+ *
+ * @author original author unknown
  */
 public class ButtonGroup implements Serializable
 {
Index: javax/swing/CellRendererPane.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/CellRendererPane.java,v
retrieving revision 1.9
diff -u -r1.9 CellRendererPane.java
--- javax/swing/CellRendererPane.java   21 Jul 2005 14:59:31 -0000      1.9
+++ javax/swing/CellRendererPane.java   26 Jul 2005 15:29:36 -0000
@@ -48,12 +48,11 @@
 import javax.accessibility.AccessibleRole;
 
 /**
- * The CellRendererPane's purpose is to paint the cells of JList, JTable and
- * JTree. It intercepts the usual paint tree, so that we don't walk up and
+ * Paints the cells of JList, JTable and JTree.
+ * It intercepts the usual paint tree, so that we don't walk up and
  * repaint everything.
  *
- * @author     Andrew Selkirk
- * @version    1.0
+ * @author Andrew Selkirk
  */
 public class CellRendererPane
   extends Container
@@ -62,7 +61,7 @@
   private static final long serialVersionUID = -7642183829532984273L;
 
   /**
-   * AccessibleCellRendererPane
+   * Provides accessibility support for CellRendererPanes.
    */
   protected class AccessibleCellRendererPane extends AccessibleAWTContainer
   {
Index: javax/swing/ComponentInputMap.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/ComponentInputMap.java,v
retrieving revision 1.7
diff -u -r1.7 ComponentInputMap.java
--- javax/swing/ComponentInputMap.java  21 Jul 2005 14:59:31 -0000      1.7
+++ javax/swing/ComponentInputMap.java  26 Jul 2005 15:29:36 -0000
@@ -39,6 +39,9 @@
 
 
 /**
+ * An address@hidden InputMap} that is associated with a particular 
address@hidden JComponent}.
+ * The component is notified when its <code>ComponentInputMap</code> changes.
+ *
  * @author Andrew Selkirk
  * @author Michael Koch
  */
Index: javax/swing/DebugGraphics.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/DebugGraphics.java,v
retrieving revision 1.6
diff -u -r1.6 DebugGraphics.java
--- javax/swing/DebugGraphics.java      2 Jul 2005 20:32:46 -0000       1.6
+++ javax/swing/DebugGraphics.java      26 Jul 2005 15:29:36 -0000
@@ -50,9 +50,11 @@
 
 
 /**
- * DebugGraphics
- * @author     Andrew Selkirk
- * @version    1.0
+ * An extension of address@hidden Graphics} that can be used for debugging
+ * custom Swing widgets. <code>DebugGraphics</code> has the ability to
+ * draw slowly and can log drawing actions.
+ *
+ * @author Andrew Selkirk
  */
 public class DebugGraphics extends Graphics
 {