added some swing scaladocs

35 files changed, 208 insertions, 61 deletions

diff --git a/src/swing/scala/swing/Action.scala b/src/swing/scala/swing/Action.scala
index 46dc470558..c3a94ed65e 100644
--- a/src/swing/scala/swing/Action.scala
+++ b/src/swing/scala/swing/Action.scala
@@ -34,10 +34,12 @@ object Action {
 }
 
 /**
+ * An abstract action to be performed in reaction to user input.
+ *
  * Not every action component will honor every property of its action.
  * An action itself can generally be configured so that certain properties
  * should be ignored and instead taken from the component directly. In the
- * end, it is up to a component, which property it uses in which way.
+ * end, it is up to a component which property it uses in which way.
  *
  * @see javax.swing.Action
  */
diff --git a/src/swing/scala/swing/Alignment.scala b/src/swing/scala/swing/Alignment.scala
index 524fefe92e..e4875904c8 100644
--- a/src/swing/scala/swing/Alignment.scala
+++ b/src/swing/scala/swing/Alignment.scala
@@ -5,6 +5,8 @@ import javax.swing.SwingConstants._
 /**
  * Horizontal and vertical alignments. We sacrifice a bit of type-safety
  * for simplicity here.
+ *
+ * @see javax.swing.SwingConstants
  */
 object Alignment extends Enumeration {
   val Left = Value(LEFT)
diff --git a/src/swing/scala/swing/BorderPanel.scala b/src/swing/scala/swing/BorderPanel.scala
index 93ee4eec71..4b614272e3 100644
--- a/src/swing/scala/swing/BorderPanel.scala
+++ b/src/swing/scala/swing/BorderPanel.scala
@@ -3,6 +3,9 @@ package scala.swing
 import java.awt.BorderLayout
 
 object BorderPanel {
+  /**
+   * The position of a component in a <code>BorderPanel</code>
+   */
   object Position extends Enumeration {
     val North = Value(BorderLayout.NORTH)
     val South = Value(BorderLayout.SOUTH)
@@ -20,6 +23,10 @@ object BorderPanel {
 }
 
 /**
+ * A container that arranges its children around a central component that
+ * takes most of the space. The other children are placed on one of four
+ * borders: north, east, south, west.
+ *
  * @see javax.swing.BorderLayout
  */
 class BorderPanel extends Panel with LayoutContainer {
@@ -34,6 +41,4 @@ class BorderPanel extends Panel with LayoutContainer {
 
   protected def areValid(c: Constraints): (Boolean, String) = (true, "")
   protected def add(c: Component, l: Constraints) { peer.add(c.peer, l.toString) }
-
-
 }
diff --git a/src/swing/scala/swing/Button.scala b/src/swing/scala/swing/Button.scala
index 3e3e05aa8f..0aa93ae45b 100644
--- a/src/swing/scala/swing/Button.scala
+++ b/src/swing/scala/swing/Button.scala
@@ -4,7 +4,7 @@ import javax.swing._
 import event._
 
 /**
- * A button that can be pushed, usually to perfrom some action.
+ * A button that can be clicked, usually to perform some action.
  *
  * @see javax.swing.JButton
  */
diff --git a/src/swing/scala/swing/CheckBox.scala b/src/swing/scala/swing/CheckBox.scala
index 199179d83b..845b7f7024 100644
--- a/src/swing/scala/swing/CheckBox.scala
+++ b/src/swing/scala/swing/CheckBox.scala
@@ -3,7 +3,7 @@ package scala.swing
 import javax.swing._
 
 /**
- * Two state button that can be either be checked or not.
+ * Two state button that can either be checked or unchecked.
  *
  * @see javax.swing.JCheckBox
  */
diff --git a/src/swing/scala/swing/ComboBox.scala b/src/swing/scala/swing/ComboBox.scala
index 4e400e726c..219972d22f 100644
--- a/src/swing/scala/swing/ComboBox.scala
+++ b/src/swing/scala/swing/ComboBox.scala
@@ -9,7 +9,7 @@ object ComboBox {
   /**
    * An editor for a combo box. Let's you edit the currently selected item.
    * It is highly recommended to use the BuiltInEditor class. For anything
-   * else, one cannot guarantee that it integrated nicely into the current
+   * else, one cannot guarantee that it integrates nicely with the current
    * LookAndFeel.
    *
    * Publishes action events.
@@ -138,14 +138,8 @@ object ComboBox {
 }
 
 /**
- * Has built-in default editor and renderer that cannot be exposed.
- * They are set by the look and feel (LaF). Unfortunately, this design in
- * inherently broken, since custom editors will almost always look
- * differently. The border of the built-in text field editor, e.g., is drawn
- * by the LaF. In a custom text field editor we have no way to mirror that.
- *
- * This combo box has to be initialized with a valid selected value.
- * Otherwise it will fail.
+ * Let's the user make a selection from a list of predefined items. Visually,
+ * this is implemented as a button-like component with a pull-down menu.
  *
  * @see javax.swing.JComboBox
  */
@@ -165,15 +159,15 @@ class ComboBox[A](items: Seq[A]) extends Component with Publisher {
 
   /**
    * Sets the renderer for this combo box's items. Index -1 is
-   * passed to the renderer for the selected item (not in the popup menu).
+   * passed to the renderer for the selected item (not in the pull-down menu).
    *
-   * The underlying combo box renders all items in a ListView (both, in
-   * the pulldown menu as well as in the box itself), hence the
-   * ListView.Renderer.
+   * The underlying combo box renders all items in a <code>ListView</code>
+   * (both, in the pull-down menu as well as in the box itself), hence the
+   * <code>ListView.Renderer</code>.
    *
    * Note that the UI peer of a combo box usually changes the colors
-   * of the component to its own defaults _after_ the renderer has configured it.
-   * That's Swing's principle of most suprise.
+   * of the component to its own defaults _after_ the renderer has been
+   * configured. That's Swing's principle of most suprise.
    */
   def renderer: ListView.Renderer[A] = ListView.Renderer.wrap(peer.getRenderer)
   def renderer_=(r: ListView.Renderer[A]) { peer.setRenderer(r.peer) }
@@ -185,7 +179,7 @@ class ComboBox[A](items: Seq[A]) extends Component with Publisher {
   def editable: Boolean = peer.isEditable
 
   /**
-   * Makes this combo box editable. In order to do, this combo needs an
+   * Makes this combo box editable. In order to do so, this combo needs an
    * editor which is supplied by the implicit argument. For default
    * editors, see ComboBox companion object.
    */
diff --git a/src/swing/scala/swing/Component.scala b/src/swing/scala/swing/Component.scala
index 0677761d5f..6409ff1cd5 100644
--- a/src/swing/scala/swing/Component.scala
+++ b/src/swing/scala/swing/Component.scala
@@ -124,7 +124,7 @@ abstract class Component extends UIElement with Publisher {
   })
 
   /**
-   * Contains publishers for various mouse events. They are subdivided for
+   * Contains publishers for various mouse events. They are separated for
    * efficiency reasons.
    */
   object Mouse {
diff --git a/src/swing/scala/swing/Container.scala b/src/swing/scala/swing/Container.scala
index c1a2c7cc32..d51b056aba 100644
--- a/src/swing/scala/swing/Container.scala
+++ b/src/swing/scala/swing/Container.scala
@@ -4,6 +4,9 @@ import event._
 import scala.collection.mutable.Buffer
 
 object Container {
+  /**
+   * Utility trait for wrapping containers.
+   */
   trait Wrapper extends Component with Container {
     protected val _contents = new Content
     def contents: Seq[Component] = _contents
diff --git a/src/swing/scala/swing/Dialog.scala b/src/swing/scala/swing/Dialog.scala
index 05928b5dc1..d2cab71c9a 100644
--- a/src/swing/scala/swing/Dialog.scala
+++ b/src/swing/scala/swing/Dialog.scala
@@ -2,7 +2,15 @@ package scala.swing
 
 import javax.swing.{Icon, JOptionPane}
 
+/**
+ * Simple predefined dialogs.
+ *
+ * @see javax.swing.JOptionPane
+ */
 object Dialog {
+  /**
+   * The message type of a dialog.
+   */
   object Message extends Enumeration {
     val Error = Value(JOptionPane.ERROR_MESSAGE)
     val Info = Value(JOptionPane.INFORMATION_MESSAGE)
@@ -10,12 +18,20 @@ object Dialog {
     val Question = Value(JOptionPane.QUESTION_MESSAGE)
     val Plain = Value(JOptionPane.PLAIN_MESSAGE)
   }
+
+  /**
+   * The possible answers a user can select.
+   */
   object Options extends Enumeration {
     val Default = Value(JOptionPane.DEFAULT_OPTION)
     val YesNo = Value(JOptionPane.YES_NO_OPTION)
     val YesNoCancel = Value(JOptionPane.YES_NO_CANCEL_OPTION)
     val OkCancel = Value(JOptionPane.OK_CANCEL_OPTION)
   }
+
+  /**
+   * The selected result of dialog.
+   */
   object Result extends Enumeration {
     val Yes = Value(JOptionPane.YES_OPTION)
     val Ok = Yes
diff --git a/src/swing/scala/swing/FileChooser.scala b/src/swing/scala/swing/FileChooser.scala
index 92bf3c54e1..cab6abc1c0 100644
--- a/src/swing/scala/swing/FileChooser.scala
+++ b/src/swing/scala/swing/FileChooser.scala
@@ -7,7 +7,8 @@ import javax.swing.filechooser._
 object FileChooser {
   /**
    * The result of a file dialog. The precise meaning of the <code>Approve</code>
-   * result depends on the specific dialog kind.
+   * result depends on the specific dialog type. Could be "save" or "open" for
+   * example.
    */
   object Result extends Enumeration {
     val Cancel = Value(JFileChooser.CANCEL_OPTION)
diff --git a/src/swing/scala/swing/FlowPanel.scala b/src/swing/scala/swing/FlowPanel.scala
index 3c3c7d1f31..f8eb00a71e 100644
--- a/src/swing/scala/swing/FlowPanel.scala
+++ b/src/swing/scala/swing/FlowPanel.scala
@@ -13,7 +13,7 @@ object FlowPanel {
 }
 
 /**
- * A panel that lays out its contents horizontally, one after the other.
+ * A panel that arranges its contents horizontally, one after the other.
  * If they don't fit, this panel will try to insert line breaks.
  *
  * @see java.awt.FlowLayout
diff --git a/src/swing/scala/swing/FormattedTextField.scala b/src/swing/scala/swing/FormattedTextField.scala
index b771078f37..4be61b6cb1 100644
--- a/src/swing/scala/swing/FormattedTextField.scala
+++ b/src/swing/scala/swing/FormattedTextField.scala
@@ -5,6 +5,9 @@ import java.awt.event._
 import event._
 
 object FormattedTextField {
+  /**
+   * The behavior of a formatted text field when it loses its focus.
+   */
   object FocusLostBehavior extends Enumeration {
     val Commit = Value(JFormattedTextField.COMMIT)
     val CommitOrRevert = Value(JFormattedTextField.COMMIT_OR_REVERT)
@@ -14,6 +17,8 @@ object FormattedTextField {
 }
 
 /**
+ * A text field with formatted input.
+ *
  * @see javax.swing.JFormattedTextField
  */
 class FormattedTextField(format: java.text.Format) extends TextComponent {
diff --git a/src/swing/scala/swing/Frame.scala b/src/swing/scala/swing/Frame.scala
index 9d0162356f..fc2ebe297d 100644
--- a/src/swing/scala/swing/Frame.scala
+++ b/src/swing/scala/swing/Frame.scala
@@ -4,7 +4,7 @@ import javax.swing._
 import event._
 
 /**
- * A decorated window.
+ * A window with decoration such as a title, border, and action buttons.
  *
  * @see javax.swing.JFrame
  */
diff --git a/src/swing/scala/swing/GUIApplication.scala b/src/swing/scala/swing/GUIApplication.scala
index e008b5422d..999ef3971f 100644
--- a/src/swing/scala/swing/GUIApplication.scala
+++ b/src/swing/scala/swing/GUIApplication.scala
@@ -11,6 +11,9 @@ class GUIApplication {
     //JFrame.setDefaultLookAndFeelDecorated(defaultLookAndFeelDecorated)
   }
 
+  /**
+   * Initializes the framework and runs the given program.
+   */
   def run(prog: => Unit): Unit =
     SwingUtilities.invokeLater {
       new Runnable() {
diff --git a/src/swing/scala/swing/GridBagPanel.scala b/src/swing/scala/swing/GridBagPanel.scala
index 8e42de28a1..d27299b023 100644
--- a/src/swing/scala/swing/GridBagPanel.scala
+++ b/src/swing/scala/swing/GridBagPanel.scala
@@ -33,7 +33,7 @@ object GridBagPanel {
 }
 
 /**
- * A panel that lays out its children in a grid. Layout details can be
+ * A panel that arranges its children in a grid. Layout details can be
  * given for each cell of the grid.
  *
  * @see java.awt.GridBagLayout
@@ -44,6 +44,10 @@ class GridBagPanel extends Panel with LayoutContainer {
 
   private def layoutManager = peer.getLayout.asInstanceOf[java.awt.GridBagLayout]
 
+  /**
+   * Convenient conversion from xy-coords given as pairs to
+   * grid bag constraints.
+   */
   implicit def pair2Constraints(p: (Int, Int)): Constraints = {
     val c = new Constraints
     c.gridx = p._1
diff --git a/src/swing/scala/swing/GridPanel.scala b/src/swing/scala/swing/GridPanel.scala
index 0d92b8117f..1a1de23d2a 100644
--- a/src/swing/scala/swing/GridPanel.scala
+++ b/src/swing/scala/swing/GridPanel.scala
@@ -6,6 +6,7 @@ object GridPanel {
 
 /**
  * A panel that lays out its contents in a uniform grid.
+ *
  * @see java.awt.GridLayout
  */
 class GridPanel(rows0: Int, cols0: Int) extends Panel with SequentialContainer.Wrapper {
diff --git a/src/swing/scala/swing/Label.scala b/src/swing/scala/swing/Label.scala
index 40189475aa..defa45fa01 100644
--- a/src/swing/scala/swing/Label.scala
+++ b/src/swing/scala/swing/Label.scala
@@ -4,7 +4,7 @@ import javax.swing._
 import scala.swing.Swing._
 
 /**
- * A label component.
+ * A label component that display either a text, an icon, or both.
  *
  * @see javax.swing.JLabel
  */
diff --git a/src/swing/scala/swing/ListView.scala b/src/swing/scala/swing/ListView.scala
index 6d9a6354bf..81581a5a9e 100644
--- a/src/swing/scala/swing/ListView.scala
+++ b/src/swing/scala/swing/ListView.scala
@@ -6,6 +6,9 @@ import event._
 import java.awt.Color
 
 object ListView {
+  /**
+   * The supported modes of user selections.
+   */
   object IntervalMode extends Enumeration {
     val Single = Value(ListSelectionModel.SINGLE_SELECTION)
     val SingleInterval = Value(ListSelectionModel.SINGLE_INTERVAL_SELECTION)
@@ -19,23 +22,43 @@ object ListView {
   object Renderer {
     def wrap[A](r: ListCellRenderer): Renderer[A] = new Wrapped[A](r)
 
+    /**
+     * Wrapper for <code>javax.swing.ListCellRenderer<code>s
+     */
   	class Wrapped[A](override val peer: ListCellRenderer) extends Renderer[A] {
   	  def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int) = {
         Component.wrap(peer.getListCellRendererComponent(list.peer, a, index, isSelected, hasFocus).asInstanceOf[JComponent])
       }
   	}
 
+    /**
+     * Returns a renderer for items of type <code>A</code>. The given function
+     * converts items of type <code>A</code> to items of type <code>B</code>
+     * for which a renderer is implicitly given. This allows chaining of
+     * renderers, e.g.:
+     *
+     * <code>
+     * case class Person(name: String, email: String)
+     * val persons = List(Person("John", "j.doe@a.com"), Person("Mary", "m.jane@b.com"))
+     * new ListView(persons) {
+     *   renderer = ListView.Renderer(_.name)
+     * }
+     * </code>
+     */
     def apply[A,B](f: A => B)(implicit renderer: Renderer[B]): Renderer[A] = new Renderer[A] {
       def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int): Component =
         renderer.componentFor(list, isSelected, hasFocus, f(a), index)
     }
   }
 
-  /*def Renderer[A,B](f: A => B)(implicit renderer: Renderer[B]): Renderer[A] = new Renderer[A] {
-    def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int): Component =
-      renderer.componentFor(list, isSelected, hasFocus, f(a), index)
-  }*/
-
+  /**
+   * Item renderer for a list view. This is contravariant on the type of the
+   * items, so a more general renderer can be used in place of a more specific
+   * one. For instance, an <code>Any</code> renderer can be used for a list view
+   * of strings.
+   *
+   * @see javax.swing.ListCellRenderer
+   */
   abstract class Renderer[-A] {
     def peer: ListCellRenderer = new ListCellRenderer {
       def getListCellRendererComponent(list: JList, a: Any, index: Int, isSelected: Boolean, hasFocus: Boolean) =
@@ -47,7 +70,7 @@ object ListView {
   /**
    * A default renderer that maintains a single component for item rendering
    * and preconfigures it to sensible defaults. It is polymorphic on the
-   * components type so clients can easily use component specific attributes
+   * component's type so clients can easily use component specific attributes
    * during configuration.
    */
   abstract class AbstractRenderer[-A, C<:Component](protected val component: C) extends Renderer[A] {
@@ -58,6 +81,8 @@ object ListView {
 
     /**
      * Standard preconfiguration that is commonly done for any component.
+     * This includes foreground and background colors, as well as colors
+     * of item selections.
      */
     def preConfigure(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int) {
       if (isSelected) {
@@ -83,6 +108,11 @@ object ListView {
     }
   }
 
+  /**
+   * A generic renderer that uses Swing's built-in renderers. If there is no
+   * specific renderer for a type, this renderer falls back to a renderer
+   * that renders the string returned from an item's <code>toString</code>.
+   */
   implicit object GenericRenderer extends Renderer[Any] {
     override lazy val peer: ListCellRenderer = new DefaultListCellRenderer
     def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: Any, index: Int): Component = {
@@ -94,8 +124,10 @@ object ListView {
 }
 
 /**
- * A component that displays its elements in a list. Named
- * <code>ListView</code> to avoid a clash with the frequently used
+ * A component that displays a number of elements in a list. A list view does
+ * not support inline editing of items. If you need it, use a table view instead.
+ *
+ * Named <code>ListView</code> to avoid a clash with the frequently used
  * <code>scala.List</code>
  *
  * @see javax.swing.JList
@@ -134,6 +166,9 @@ class ListView[A] extends Component {
     })
   }
 
+  /**
+   * The current item selection.
+   */
   object selection extends Publisher {
     protected abstract class Indices[A](a: =>Seq[A]) extends scala.collection.mutable.Set[A] {
       def -=(n: A)
@@ -143,6 +178,9 @@ class ListView[A] extends Component {
       def elements = a.elements
     }
 
+    /**
+     * The indices of the currently selected items.
+     */
     object indices extends Indices(peer.getSelectedIndices) {
       def -=(n: Int) { peer.removeSelectionInterval(n,n) }
       def +=(n: Int) { peer.addSelectionInterval(n,n) }
@@ -152,6 +190,9 @@ class ListView[A] extends Component {
     }
     def selectIndices(ind: Int*) = peer.setSelectedIndices(ind.toArray)
 
+    /**
+     * The currently selected items.
+     */
     object items extends SeqProxy[A] {
       def self = peer.getSelectedValues.map(_.asInstanceOf[A])
       def leadIndex: Int = peer.getSelectionModel.getLeadSelectionIndex
diff --git a/src/swing/scala/swing/MainFrame.scala b/src/swing/scala/swing/MainFrame.scala
index 018866ba2b..ae594448ef 100644
--- a/src/swing/scala/swing/MainFrame.scala
+++ b/src/swing/scala/swing/MainFrame.scala
@@ -3,8 +3,8 @@ package scala.swing
 import event._
 
 /**
- * A frame that can be used for main application windows. Quits the
- * application on close.
+ * A frame that can be used for main application windows. Shuts down the
+ * framework and quits the application when closed.
  */
 class MainFrame extends Frame {
   reactions += {
diff --git a/src/swing/scala/swing/Menu.scala b/src/swing/scala/swing/Menu.scala
index 418439435d..7f85688125 100644
--- a/src/swing/scala/swing/Menu.scala
+++ b/src/swing/scala/swing/Menu.scala
@@ -4,6 +4,8 @@ import scala.collection.mutable._
 import javax.swing._
 
 /**
+ * A menu bar. Each window can contain at most one. Contains a number of menus.
+ *
  * @see javax.swing.JMenuBar
  */
 class MenuBar extends Component with SequentialContainer.Wrapper {
@@ -16,13 +18,9 @@ class MenuBar extends Component with SequentialContainer.Wrapper {
   //def helpMenu_=(m: Menu) { peer.setHelpMenu(m.peer) }
 }
 
-/*trait MenuElement extends Component {
-  def peer: javax.swing.JComponent with javax.swing.MenuElement
-
-  def subElements: Seq[MenuElement] = peer.getSubElements.map(Component.wrapperFor(_))
-}*/
-
 /**
+ * A menu item that can be used in a menu.
+ *
  * @see javax.swing.JMenuItem
  */
 class MenuItem(title0: String) extends AbstractButton {
@@ -34,6 +32,8 @@ class MenuItem(title0: String) extends AbstractButton {
 }
 
 /**
+ * A menu. Contains menu items. Being a menu item itself, menus can be nested.
+ *
  * @see javax.swing.JMenu
  */
 class Menu(title0: String) extends MenuItem(title0) with SequentialContainer.Wrapper { self: Menu =>
@@ -41,12 +41,16 @@ class Menu(title0: String) extends MenuItem(title0) with SequentialContainer.Wra
 }
 
 /**
+ * A menu item with a radio button.
+ *
  * @see javax.swing.JRadioButtonMenuItem
  */
 class RadioMenuItem(title0: String) extends MenuItem(title0) {
   override lazy val peer: JRadioButtonMenuItem = new JRadioButtonMenuItem(title0)
 }
 /**
+ * A menu item with a check box.
+ *
  * @see javax.swing.JCheckBoxMenuItem
  */
 class CheckMenuItem(title0: String) extends MenuItem(title0) {
diff --git a/src/swing/scala/swing/PasswordField.scala b/src/swing/scala/swing/PasswordField.scala
index 58a4150fb8..4769759a0c 100644
--- a/src/swing/scala/swing/PasswordField.scala
+++ b/src/swing/scala/swing/PasswordField.scala
@@ -5,6 +5,8 @@ import java.awt.event._
 import event._
 
 /**
+ * A password field, that displays a replacement character for each character in the password.
+ *
  * @see javax.swing.JPasswordField
  */
 class PasswordField(text0: String, columns0: Int) extends TextField(text0, columns0) {
diff --git a/src/swing/scala/swing/ProgressBar.scala b/src/swing/scala/swing/ProgressBar.scala
index 463c2fba56..68d815f181 100644
--- a/src/swing/scala/swing/ProgressBar.scala
+++ b/src/swing/scala/swing/ProgressBar.scala
@@ -3,6 +3,10 @@ package scala.swing
 import event._
 
 /**
+ * A bar indicating progress of some action. Can be in indeterminate mode,
+ * in which it indicates that the action is in progress (usually by some
+ * animation) but does not indicate the amount of work done or to be done.
+ *
  * @see javax.swing.JProgressBar
  */
 class ProgressBar extends Component with Orientable {
diff --git a/src/swing/scala/swing/Publisher.scala b/src/swing/scala/swing/Publisher.scala
index bcefc6c42e..4b26e9e74e 100644
--- a/src/swing/scala/swing/Publisher.scala
+++ b/src/swing/scala/swing/Publisher.scala
@@ -4,26 +4,35 @@ import scala.collection.mutable._
 import event.Event
 
 /**
- * Notifies subscribed observers when a event is published.
+ * Notifies registered reactions when an event is published. Publishers are also
+ * reactors and listen to themselves per default as a convenience.
+ *
+ * In order to reduce memory leaks, reactions are weakly referenced by default,
+ * unless they implement <code>Reactions.StronglyReferenced</code>. This way,
+ * the lifetime of reactions are more easily bound to the registering object,
+ * which are reactors in common client code and hold strong references to their
+ * reactions. As a result, reactors can be garbage collected even though they
+ * still have reactions registered at some publisher, but usually not vice versa
+ * since reactors (strongly) reference publishers they are interested in.
  */
 trait Publisher extends Reactor {
   import Reactions._
-  // TODO: optionally weak references
-  protected var listeners = new RefSet[Reaction] {
+
+  protected val listeners = new RefSet[Reaction] {
     import scala.ref._
     val underlying = new HashSet[Reference[Reaction]]
     protected def Ref(a: Reaction) = a match {
-      case a: StronglyReferenced => new StrongReference[Reaction](a) with super.Ref[Reaction] {
-        type _$1 = Reaction // FIXME: what's going on here?
-      }
-      case _ => new WeakReference[Reaction](a, referenceQueue) with super.Ref[Reaction] {
-        type _$1 = Reaction // FIXME: what's going on here?
-      }
+      case a: StronglyReferenced => new StrongReference[Reaction](a) with super.Ref[Reaction]
+      case _ => new WeakReference[Reaction](a, referenceQueue) with super.Ref[Reaction]
     }
   }
 
   def subscribe(listener: Reaction) { listeners += listener }
   def unsubscribe(listener: Reaction) { listeners -= listener }
+
+  /**
+   * Notify all registered reactions.
+   */
   def publish(e: Event) { for (val l <- listeners) l(e) }
 
   listenTo(this)
diff --git a/src/swing/scala/swing/Reactions.scala b/src/swing/scala/swing/Reactions.scala
index fce1fe3956..8d5c4ae576 100644
--- a/src/swing/scala/swing/Reactions.scala
+++ b/src/swing/scala/swing/Reactions.scala
@@ -21,7 +21,7 @@ object Reactions {
   /**
    * A Reaction implementing this trait is strongly referenced in the reaction list
    */
-  trait StronglyReferenced // TODO: implement in Publisher
+  trait StronglyReferenced
 
   class Wrapper(listener: Any)(r: Reaction) extends Reaction with StronglyReferenced with Proxy {
     def self = listener
@@ -30,7 +30,9 @@ object Reactions {
   }
 }
 
-
+/**
+ * Used by reactors to let clients register custom event reactions.
+ */
 abstract class Reactions extends Reactions.Reaction {
   /**
    * Add a reaction.
diff --git a/src/swing/scala/swing/Reactor.scala b/src/swing/scala/swing/Reactor.scala
index 002002d3f9..1b2d806d85 100644
--- a/src/swing/scala/swing/Reactor.scala
+++ b/src/swing/scala/swing/Reactor.scala
@@ -1,7 +1,13 @@
 package scala.swing
 
+/**
+ * The counterpart to publishers. Listens to events from registered publishers.
+ */
 trait Reactor {
-  val reactions = new Reactions.Impl
+  /**
+   * All reactions of this reactor.
+   */
+  val reactions: Reactions = new Reactions.Impl
   /**
    * Listen to the given publisher as long as <code>deafTo</code> isn't called for
    * them.
diff --git a/src/swing/scala/swing/ScrollPane.scala b/src/swing/scala/swing/ScrollPane.scala
index a451745631..a3eea8a715 100644
--- a/src/swing/scala/swing/ScrollPane.scala
+++ b/src/swing/scala/swing/ScrollPane.scala
@@ -3,8 +3,8 @@ package scala.swing
 import javax.swing.JScrollPane
 
 /**
- * Can have at most a single child that is put inside a canvas that can be
- * scrolled.
+ * Can have at most a single child component. It display it inside a canvas (the viewport)
+ * that can be scrolled.
  *
  * @see javax.swing.JScrollPane
  */
@@ -16,8 +16,19 @@ class ScrollPane extends Component with Container {
   }
   def contents: Seq[Component] =
     List(Component.wrapperFor(peer.getViewport.getView.asInstanceOf[javax.swing.JComponent]))
+
+  /**
+   * Sets the single child.
+   */
   def contents_=(c: Component) { peer.setViewportView(c.peer) }
 
+  /**
+   * The component being displayed in this pane's row header.
+   *
+   * If you want to create a row header for lists or tables, you probably
+   * want to let the row header be a list view with the same row height as
+   * the viewport component.
+   */
   def rowHeaderView: Option[Component] = Swing.toOption(peer.getRowHeader.getView).map(Component.wrapperFor(_))
   def rowHeaderView_=(c: Component) = peer.setRowHeaderView(c.peer)
   def rowHeaderView_=(c: Option[Component]) = peer.setRowHeaderView(Swing.toNull(c.map(_.peer)))
diff --git a/src/swing/scala/swing/Scrollable.scala b/src/swing/scala/swing/Scrollable.scala
index 3a2acb8426..06c283ce42 100644
--- a/src/swing/scala/swing/Scrollable.scala
+++ b/src/swing/scala/swing/Scrollable.scala
@@ -3,7 +3,7 @@ package scala.swing
 import java.awt.Rectangle
 
 /**
- * A component that specially suitable for being placed inside a
+ * A component that is specially suitable for being placed inside a
  * <code>ScrollPane</code>.
  *
  * @see javax.swing.Scrollable
diff --git a/src/swing/scala/swing/SequentialContainer.scala b/src/swing/scala/swing/SequentialContainer.scala
index a9b663c773..b5cfb65b9b 100644
--- a/src/swing/scala/swing/SequentialContainer.scala
+++ b/src/swing/scala/swing/SequentialContainer.scala
@@ -3,6 +3,9 @@ package scala.swing
 import scala.collection.mutable.Buffer
 
 object SequentialContainer {
+  /**
+   * Utility trait for wrapping sequential containers.
+   */
   trait Wrapper extends Component with SequentialContainer with Container.Wrapper {
     override val contents: Buffer[Component] = new Content
     //def contents_=(c: Component*)  { contents.clear(); contents ++= c }
@@ -10,7 +13,7 @@ object SequentialContainer {
 }
 
 /**
- * A container that contains children in a certain order.
+ * A container that contains children in a specific sequential order.
  */
 trait SequentialContainer extends Container {
   override def contents: Buffer[Component]
diff --git a/src/swing/scala/swing/SimpleGUIApplication.scala b/src/swing/scala/swing/SimpleGUIApplication.scala
index 436ba1e10b..2cc5078837 100644
--- a/src/swing/scala/swing/SimpleGUIApplication.scala
+++ b/src/swing/scala/swing/SimpleGUIApplication.scala
@@ -2,6 +2,10 @@ package scala.swing
 
 import javax.swing._
 
+/**
+ * Extend this class for most simple UI applications. Clients need to implement the
+ * <code>top</code> method. Framework intialization is done by this class.
+ */
 abstract class SimpleGUIApplication extends GUIApplication {
   def top: Frame
 
diff --git a/src/swing/scala/swing/Slider.scala b/src/swing/scala/swing/Slider.scala
index b66c37dc8e..36e352bbc3 100644
--- a/src/swing/scala/swing/Slider.scala
+++ b/src/swing/scala/swing/Slider.scala
@@ -3,6 +3,8 @@ package scala.swing
 import event._
 
 /**
+ * Lets users select a value from a given range. Visually, this is represented
+ * as a draggable knob on a horizontal or vertical bar.
  *
  * Fires a ValueChanged event whenever the slider's value changes and
  * when the knob is released.
diff --git a/src/swing/scala/swing/SplitPane.scala b/src/swing/scala/swing/SplitPane.scala
index a5026adad7..2cd06e7a5d 100644
--- a/src/swing/scala/swing/SplitPane.scala
+++ b/src/swing/scala/swing/SplitPane.scala
@@ -4,6 +4,10 @@ import event._
 import Swing._
 
 /**
+ * A container with exactly two children. Arranges them side by side, either
+ * horizontally or vertically. Displays a draggable divider component between
+ * them that lets the user adjust the size ratio of the children.
+ *
  * @see javax.swing.JSplitPane
  */
 class SplitPane(o: Orientation.Value, left: Component, right: Component) extends Component with Container with Orientable {
diff --git a/src/swing/scala/swing/TabbedPane.scala b/src/swing/scala/swing/TabbedPane.scala
index e86c1f060c..3661c6988a 100644
--- a/src/swing/scala/swing/TabbedPane.scala
+++ b/src/swing/scala/swing/TabbedPane.scala
@@ -56,6 +56,10 @@ object TabbedPane {
 }
 
 /**
+ * Displays the contents of one of several pages at a time. For each page a tab is
+ * visible at all times. The user can click on one of these tabs to move the
+ * corresponding page to the front.
+ *
  * @see javax.swing.JTabbedPane
  */
 class TabbedPane extends Component with Publisher {
@@ -95,6 +99,9 @@ class TabbedPane extends Component with Publisher {
    */
   def tabPlacement(b: Alignment.Value) { peer.setTabPlacement(b.id) }
 
+  /**
+   * The current page selection
+   */
   object selection extends Publisher {
     def page: Page = pages(index)
     def page_=(p: Page) { index = p.index }
diff --git a/src/swing/scala/swing/Table.scala b/src/swing/scala/swing/Table.scala
index fbd4904c5f..15e7128304 100644
--- a/src/swing/scala/swing/Table.scala
+++ b/src/swing/scala/swing/Table.scala
@@ -26,6 +26,11 @@ object Table {
     val Row, Column, Cell, None = Value
   }
 
+  /**
+   * A table item renderer.
+   *
+   * @see javax.swing.table.TableCellRenderer
+   */
   abstract class Renderer[-A] {
     def peer: TableCellRenderer = new TableCellRenderer {
       def getTableCellRendererComponent(table: JTable, value: AnyRef, isSelected: Boolean, hasFocus: Boolean, row: Int, column: Int) = {
@@ -83,6 +88,8 @@ object Table {
 }
 
 /**
+ * Displays a matrix of items.
+ *
  * @see javax.swing.JTable
  */
 class Table extends Component with Scrollable with Publisher {
diff --git a/src/swing/scala/swing/ToggleButton.scala b/src/swing/scala/swing/ToggleButton.scala
index 0f04aa9f35..cc7827ddb7 100644
--- a/src/swing/scala/swing/ToggleButton.scala
+++ b/src/swing/scala/swing/ToggleButton.scala
@@ -4,7 +4,8 @@ import javax.swing._
 import event._
 
 /**
- * A two state button with a push button like UI. Usually used in tool bars.
+ * A two state button with a push button like user interface.
+ * Usually used in tool bars.
  *
  * @see javax.swing.JToggleButton
  */
diff --git a/src/swing/scala/swing/UIElement.scala b/src/swing/scala/swing/UIElement.scala
index d20bff1ef3..c1a887269b 100644
--- a/src/swing/scala/swing/UIElement.scala
+++ b/src/swing/scala/swing/UIElement.scala
@@ -3,7 +3,11 @@ package scala.swing
 import java.awt.{Color, Cursor, Font, Dimension}
 
 /**
- * The base trait of all user interface elements.
+ * The base trait of all user interface elements. Subclasses can be divided
+ * into two groups, top-level elements such as windows and dialogs, and
+ * <code>Component</code>s.
+ *
+ * @see java.awt.Component
  */
 trait UIElement extends Proxy {
   def peer: java.awt.Component