more scaladocs for swing

7 files changed, 49 insertions, 12 deletions

diff --git a/src/swing/scala/swing/Component.scala b/src/swing/scala/swing/Component.scala
index 6409ff1cd5..e2974edb21 100644
--- a/src/swing/scala/swing/Component.scala
+++ b/src/swing/scala/swing/Component.scala
@@ -7,6 +7,9 @@ import java.awt.event._
 import javax.swing.JComponent
 import javax.swing.border.Border
 
+/**
+ * Utility methods, mostly for wrapping components.
+ */
 object Component {
   private val ClientKey = "scala.swingWrapper"
 
@@ -27,6 +30,10 @@ object Component {
 
 /**
  * Base class for all UI elements that can be displayed in a window.
+ * Components are publishers that fire the following event classes:
+ * ComponentEvent, FocusEvent, FontChanged, ForegroundChanged, BackgroundChanged.
+ *
+ * @note [Java Swing] Unlike in Java Swing, not all components are also containers.
  *
  * @see javax.swing.JComponent
  */
diff --git a/src/swing/scala/swing/Container.scala b/src/swing/scala/swing/Container.scala
index d51b056aba..285d1965d7 100644
--- a/src/swing/scala/swing/Container.scala
+++ b/src/swing/scala/swing/Container.scala
@@ -5,7 +5,8 @@ import scala.collection.mutable.Buffer
 
 object Container {
   /**
-   * Utility trait for wrapping containers.
+   * Utility trait for wrapping containers. Provides an immutable
+   * implementation of the contents member.
    */
   trait Wrapper extends Component with Container {
     protected val _contents = new Content
@@ -39,9 +40,14 @@ object Container {
 }
 
 /**
- * A UI element that can contain <code>Component</code>s, such as windows,
- * panels, and menus.
+ * The base traits for UI elements that can contain <code>Component</code>s.
+ *
+ * @note [Java Swing] This is not the wrapper for java.awt.Container but a trait
+ * that extracts a common interface for components, menus, and windows.
  */
 trait Container extends UIElement {
+  /**
+   * The child components of this container.
+   */
   def contents: Seq[Component]
 }
\ No newline at end of file
diff --git a/src/swing/scala/swing/LayoutContainer.scala b/src/swing/scala/swing/LayoutContainer.scala
index 960c87e426..d052b9d27a 100644
--- a/src/swing/scala/swing/LayoutContainer.scala
+++ b/src/swing/scala/swing/LayoutContainer.scala
@@ -4,17 +4,23 @@ import javax.swing.JComponent
 import scala.collection.mutable.Map
 
 /**
- * A container that associates layout constraints with its children.
- * See GridBagPanel for an example.
+ * A container that associates layout constraints of member type Constraints
+ * with its children. See GridBagPanel for an example container with custom
+ * constraints.
+ *
+ * @note [Java Swing] In scala.swing, panels and layout managers are
+ * combined into subclasses of this base class. This approach allows for typed
+ * component constraints.
  */
 trait LayoutContainer extends Container.Wrapper {
   /**
-   * The specific type of constraints.
+   * The type of component constraints for this container.
    */
   type Constraints <: AnyRef
 
   /**
-   * Used to obtain the constraints from a Swing layout manager.
+   * Obtains the constraints for the given component from the underlying
+   * Swing layout manager.
    */
   protected def constraintsFor(c: Component): Constraints
   /**
@@ -23,13 +29,19 @@ trait LayoutContainer extends Container.Wrapper {
    */
   protected def areValid(c: Constraints): (Boolean, String)
   /**
-   * Adds the component to the layout manager and the peer.
+   * Adds a component with the given constraints to the underlying layout
+   * manager and the component peer.
    */
   protected def add(comp: Component, c: Constraints)
 
   /**
    * A map of components to the associated layout constraints.
-   * Any element in this map is automatically added to this panel.
+   * Any element in this map is automatically added to the contents of this
+   * panel. Therefore, specifying the layout of a component via
+   *
+   * layout(myComponent) = myConstraints
+   *
+   * also ensures that myComponent is properly add to this container.
    */
   def layout: Map[Component, Constraints] = new Map[Component, Constraints] {
     def -=(c: Component) { _contents -= c }
diff --git a/src/swing/scala/swing/Panel.scala b/src/swing/scala/swing/Panel.scala
index 579d23220a..12ad54ab4f 100644
--- a/src/swing/scala/swing/Panel.scala
+++ b/src/swing/scala/swing/Panel.scala
@@ -1,7 +1,7 @@
 package scala.swing
 
 /**
- * A component that can contain other components, such as layout panels.
+ * A component that can contain other components.
  *
  * @see javax.swing.JPanel
  */
diff --git a/src/swing/scala/swing/Separator.scala b/src/swing/scala/swing/Separator.scala
index 94e467a3b0..c7b36a5814 100644
--- a/src/swing/scala/swing/Separator.scala
+++ b/src/swing/scala/swing/Separator.scala
@@ -10,4 +10,4 @@ import javax.swing._
 class Separator(o: Orientation.Value) extends Component with Oriented {
   override lazy val peer: JSeparator = new JSeparator(o.id)
   def this() = this(Orientation.Horizontal)
-}
+}
\ No newline at end of file
diff --git a/src/swing/scala/swing/SequentialContainer.scala b/src/swing/scala/swing/SequentialContainer.scala
index b5cfb65b9b..5de7e15a22 100644
--- a/src/swing/scala/swing/SequentialContainer.scala
+++ b/src/swing/scala/swing/SequentialContainer.scala
@@ -13,9 +13,14 @@ object SequentialContainer {
 }
 
 /**
- * A container that contains children in a specific sequential order.
+ * A container for which a sequential order of children makes sense, such as
+ * flow panels, or menus. Its contents are mutable.
  */
 trait SequentialContainer extends Container {
+  /**
+   * The mutable child components of this container. The order matters and
+   * usually indicates the layout of the children.
+   */
   override def contents: Buffer[Component]
   //def contents_=(c: Component*)
 }
diff --git a/src/swing/scala/swing/UIElement.scala b/src/swing/scala/swing/UIElement.scala
index 6635772027..4e54175117 100644
--- a/src/swing/scala/swing/UIElement.scala
+++ b/src/swing/scala/swing/UIElement.scala
@@ -7,9 +7,16 @@ import java.awt.{Color, Cursor, Font, Dimension}
  * of two groups: top-level elements such as windows and dialogs, or
  * <code>Component</code>s.
  *
+ * @note [Java Swing] This trait does not have an exact counterpart in
+ * Java Swing. The peer is of type java.awt.Component since this is the
+ * least common upper bound of possible underlying peers.
+ *
  * @see java.awt.Component
  */
 trait UIElement extends Proxy {
+  /**
+   * The underlying Swing peer.
+   */
   def peer: java.awt.Component
   def self = peer