2005-07-26 Roman Kennke <roman@kennke.org>

	* 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.

14 files changed, 82 insertions, 30 deletions

diff --git a/ChangeLog b/ChangeLog
index 3018794cc..ff0a38894 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2005-07-26  Roman Kennke  <roman@kennke.org>
+
+	* 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.
+
 2005-07-26  Mark Wielaard  <mark@klomp.org>
 
 	* java/text/DateFormat.java (equals): Reimplement.
diff --git a/javax/swing/AbstractAction.java b/javax/swing/AbstractAction.java
index 6bb423394..da65bdd1d 100644
--- a/javax/swing/AbstractAction.java
+++ b/javax/swing/AbstractAction.java
@@ -50,8 +50,7 @@ import javax.swing.event.SwingPropertyChangeSupport;
 /**
  * A base class for implementing the {@link Action} interface.
  * 
- * @author	Andrew Selkirk
- * @version	1.0
+ * @author Andrew Selkirk
  */
 public abstract class AbstractAction
   implements Action, Cloneable, Serializable
diff --git a/javax/swing/AbstractButton.java b/javax/swing/AbstractButton.java
index 806809dad..21c4fc0a2 100644
--- a/javax/swing/AbstractButton.java
+++ b/javax/swing/AbstractButton.java
@@ -65,18 +65,13 @@ import javax.swing.text.AttributeSet;
 
 
 /**
- * <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
diff --git a/javax/swing/AbstractCellEditor.java b/javax/swing/AbstractCellEditor.java
index 86d3017f7..4ed15809a 100644
--- a/javax/swing/AbstractCellEditor.java
+++ b/javax/swing/AbstractCellEditor.java
@@ -46,11 +46,10 @@ import javax.swing.event.ChangeEvent;
 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
diff --git a/javax/swing/AbstractListModel.java b/javax/swing/AbstractListModel.java
index df09ae205..8973e5292 100644
--- a/javax/swing/AbstractListModel.java
+++ b/javax/swing/AbstractListModel.java
@@ -46,11 +46,10 @@ import javax.swing.event.ListDataEvent;
 import javax.swing.event.ListDataListener;
 
 /**
- * AbstractListModel
+ * Provides standard implementations of some methods in {@link ListModel}.
  *
  * @author Ronald Veldema
  * @author Andrew Selkirk
- * @version 1.0
  */
 public abstract class AbstractListModel implements ListModel, Serializable
 {
diff --git a/javax/swing/AbstractSpinnerModel.java b/javax/swing/AbstractSpinnerModel.java
index 05a98923f..d61113b08 100644
--- a/javax/swing/AbstractSpinnerModel.java
+++ b/javax/swing/AbstractSpinnerModel.java
@@ -45,9 +45,10 @@ import javax.swing.event.ChangeListener;
 import javax.swing.event.EventListenerList;
 
 /**
- * AbstractSpinnerModel
- * @author	Ka-Hing Cheung
- * @version	1.0
+ * Provides standard implementations for some of the methods in
+ * {@link SpinnerModel}.
+ *
+ * @author Ka-Hing Cheung
  */
 public abstract class AbstractSpinnerModel implements SpinnerModel
 {
diff --git a/javax/swing/ActionMap.java b/javax/swing/ActionMap.java
index c6092578a..c14bafdb4 100644
--- a/javax/swing/ActionMap.java
+++ b/javax/swing/ActionMap.java
@@ -49,6 +49,14 @@ import java.util.Set;
 
 
 /**
+ * Maps arbitrary keys (usually Strings) to {@link Action} instances. This
+ * is used in combination with {@link 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
  */
diff --git a/javax/swing/BorderFactory.java b/javax/swing/BorderFactory.java
index dac75871d..45cf3bbe0 100644
--- a/javax/swing/BorderFactory.java
+++ b/javax/swing/BorderFactory.java
@@ -50,6 +50,11 @@ import javax.swing.border.LineBorder;
 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()
diff --git a/javax/swing/Box.java b/javax/swing/Box.java
index 546a28220..b2cb44ace 100644
--- a/javax/swing/Box.java
+++ b/javax/swing/Box.java
@@ -60,6 +60,9 @@ public class Box extends JComponent implements Accessible
 {
   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 @@ public class Box extends JComponent implements Accessible
   {
     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
     {
diff --git a/javax/swing/BoxLayout.java b/javax/swing/BoxLayout.java
index 787e92e77..28bb53928 100644
--- a/javax/swing/BoxLayout.java
+++ b/javax/swing/BoxLayout.java
@@ -53,7 +53,8 @@ import java.util.Vector;
 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 (rveldema@cs.vu.nl)
  * @author Roman Kennke (roman@kennke.org)
diff --git a/javax/swing/ButtonGroup.java b/javax/swing/ButtonGroup.java
index bea8aea03..3de1d4b9f 100644
--- a/javax/swing/ButtonGroup.java
+++ b/javax/swing/ButtonGroup.java
@@ -43,7 +43,25 @@ import java.util.Vector;
 
 
 /**
- * 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 {@link AbstractButton}, it is normally only used for
+ * {@link JRadioButton}s, {@link JRadioButtonMenuItem}s and
+ * {@link JToggleButton}s.
+ *
+ * You could use it for {@link 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 {@link JButton}s or {@link 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
 {
diff --git a/javax/swing/CellRendererPane.java b/javax/swing/CellRendererPane.java
index d7e5e9880..886d5c5f2 100644
--- a/javax/swing/CellRendererPane.java
+++ b/javax/swing/CellRendererPane.java
@@ -48,12 +48,11 @@ import javax.accessibility.AccessibleContext;
 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 @@ public class CellRendererPane
   private static final long serialVersionUID = -7642183829532984273L;
 
   /**
-   * AccessibleCellRendererPane
+   * Provides accessibility support for CellRendererPanes.
    */
   protected class AccessibleCellRendererPane extends AccessibleAWTContainer
   {
diff --git a/javax/swing/ComponentInputMap.java b/javax/swing/ComponentInputMap.java
index 2192123a1..f95c31045 100644
--- a/javax/swing/ComponentInputMap.java
+++ b/javax/swing/ComponentInputMap.java
@@ -39,6 +39,9 @@ package javax.swing;
 
 
 /**
+ * An {@link InputMap} that is associated with a particular {@link JComponent}.
+ * The component is notified when its <code>ComponentInputMap</code> changes.
+ *
  * @author Andrew Selkirk
  * @author Michael Koch
  */
diff --git a/javax/swing/DebugGraphics.java b/javax/swing/DebugGraphics.java
index e73c120e3..137b82337 100644
--- a/javax/swing/DebugGraphics.java
+++ b/javax/swing/DebugGraphics.java
@@ -50,9 +50,11 @@ import java.text.AttributedCharacterIterator;
 
 
 /**
- * DebugGraphics
- * @author	Andrew Selkirk
- * @version	1.0
+ * An extension of {@link 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
 {