2006-04-21 David Gilbert <david.gilbert@object-refinery.com>

	* javax/swing/border/AbstractBorder.java: API doc updates,
	* javax/swing/border/BevelBorder.java: Likewise,
	* javax/swing/border/CompoundBorder.java: Likewise,
	* javax/swing/border/EtchedBorder.java: Likewise,
	* javax/swing/border/LineBorder.java: Likewise,
	* javax/swing/border/MatteBorder.java: Likewise,
	* javax/swing/border/TitledBorder.java: Likewise.

8 files changed, 102 insertions, 25 deletions

diff --git a/ChangeLog b/ChangeLog
index a9995bf67..6c55d0a5c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2006-04-21  David Gilbert  <david.gilbert@object-refinery.com>
 
+	* javax/swing/border/AbstractBorder.java: API doc updates,
+	* javax/swing/border/BevelBorder.java: Likewise,
+	* javax/swing/border/CompoundBorder.java: Likewise,
+	* javax/swing/border/EtchedBorder.java: Likewise,
+	* javax/swing/border/LineBorder.java: Likewise,
+	* javax/swing/border/MatteBorder.java: Likewise,
+	* javax/swing/border/TitledBorder.java: Likewise.
+
+2006-04-21  David Gilbert  <david.gilbert@object-refinery.com>
+
 	* gnu/javax/crypto/cipher/Anubis.java:
 	(selfTest): Use Boolean.valueOf() to avoid creating a new Boolean
 	instance,
diff --git a/javax/swing/border/AbstractBorder.java b/javax/swing/border/AbstractBorder.java
index 7cbbcdaa8..c995de1c2 100644
--- a/javax/swing/border/AbstractBorder.java
+++ b/javax/swing/border/AbstractBorder.java
@@ -1,5 +1,5 @@
 /* AbstractBorder.java -- 
-   Copyright (C) 2003 Free Software Foundation, Inc.
+   Copyright (C) 2003, 2006, Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -68,7 +68,7 @@ public abstract class AbstractBorder implements Border, Serializable
    * Performs nothing, because the default implementation provided by
    * this class is an invisible, zero-width border. Subclasses will
    * likely want to override this method, but they are not required
-   * for doing so.
+   * to do so.
    *
    * @param c the component whose border is to be painted.
    * @param g the graphics for painting.
@@ -87,9 +87,11 @@ public abstract class AbstractBorder implements Border, Serializable
   }
 
   /**
-   * Measures the width of this border.
+   * Returns the insets required for drawing this border around the specified 
+   * component.
    *
-   * @param c the component whose border is to be measured.
+   * @param c  the component that the border applies to (ignored here, 
+   *     subclasses may use it).
    *
    * @return an Insets object whose <code>left</code>, <code>right</code>,
    *         <code>top</code> and <code>bottom</code> fields indicate the
@@ -104,16 +106,23 @@ public abstract class AbstractBorder implements Border, Serializable
   }
 
   /**
-   * Determines the insets of this border. The implementation provided
-   * by AbstractButton sets the <code>left</code>, <code>right</code>,
-   * <code>top</code> and <code>bottom</code> fields of the passed
-   * <code>insets</code> parameter to zero.
+   * Returns the insets required for drawing this border around the specified 
+   * component.  The default implementation provided here sets the 
+   * <code>left</code>, <code>right</code>, <code>top</code> and 
+   * <code>bottom</code> fields of the passed <code>insets</code> parameter to 
+   * zero.
    *
-   * @param c the component whose border is to be measured
+   * @param c  the component that the border applies to (ignored here, 
+   *     subclasses may use it).
+   * @param insets  an instance that will be overwritten and returned as the 
+   *     result (<code>null</code> not permitted).  
    *
-   * @return the same object that was passed for <code>insets</code>
+   * @return The border insets (the same object that was passed as the 
+   *     <code>insets</code> argument).
    *
    * @see #getBorderInsets(Component)
+   * 
+   * @throws NullPointerException if <code>insets</code> is <code>null</code>.
    */
   public Insets getBorderInsets(Component c, Insets insets) 
   {
@@ -126,7 +135,7 @@ public abstract class AbstractBorder implements Border, Serializable
    * fills every pixel in its area when painting. Partially
    * translucent borders must return <code>false</code>, or ugly
    * artifacts can appear on screen. The default implementation
-   * provided by AbstractBorder always returns <code>false</code>.
+   * provided here always returns <code>false</code>.
    *
    * @return <code>false</code>.
    */
@@ -136,9 +145,9 @@ public abstract class AbstractBorder implements Border, Serializable
   }
 
   /**
-   * Returns a rectangle that covers the specified area minus this
-   * border.  Components that wish to determine an area into which
-   * they can safely draw without intersecting with a border might
+   * Returns a rectangle that covers the specified area minus the insets 
+   * required to draw this border.  Components that wish to determine an area 
+   * into which they can safely draw without intersecting with a border might
    * want to use this helper method.
    *
    * @param c the component in the center of this border.
@@ -146,24 +155,30 @@ public abstract class AbstractBorder implements Border, Serializable
    * @param y the vertical position of the border.
    * @param width the width of the available area for the border.
    * @param height the height of the available area for the border.
+   * 
+   * @return The interior rectangle.
    */
   public Rectangle getInteriorRectangle(Component c, int x, int y, int width,
                                         int height)
   {
-    return getInteriorRectangle (c, this, x, y, width, height);
+    return getInteriorRectangle(c, this, x, y, width, height);
   }
   
   /**
-   * Returns a rectangle that covers the specified area minus a
-   * border.  Components that wish to determine an area into which
-   * they can safely draw without intersecting with a border might
-   * want to use this helper method.
+   * Returns a rectangle that covers the specified area minus the insets 
+   * required to draw the specified border (if the border is <code>null</code>,
+   * zero insets are assumed).  Components that wish to determine an area into 
+   * which they can safely draw without intersecting with a border might want 
+   * to use this helper method.
    *
    * @param c the component in the center of this border.
+   * @param b the border (<code>null</code> permitted).
    * @param x the horizontal position of the border.
    * @param y the vertical position of the border.
    * @param width the width of the available area for the border.
    * @param height the height of the available area for the border.
+   * 
+   * @return The interior rectangle.
    */
   public static Rectangle getInteriorRectangle(Component c, Border b, int x,
                                                int y, int width, int height)
@@ -172,7 +187,7 @@ public abstract class AbstractBorder implements Border, Serializable
 
     if (b != null)
     {
-      borderInsets = b.getBorderInsets (c);
+      borderInsets = b.getBorderInsets(c);
       x += borderInsets.left;
       y += borderInsets.top;
       width -= borderInsets.left + borderInsets.right;
diff --git a/javax/swing/border/BevelBorder.java b/javax/swing/border/BevelBorder.java
index 45b758cae..403c35c04 100644
--- a/javax/swing/border/BevelBorder.java
+++ b/javax/swing/border/BevelBorder.java
@@ -305,6 +305,8 @@ public class BevelBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The color.
+   * 
    * @see #getHighlightInnerColor(java.awt.Component)
    * @see java.awt.Color#brighter()
    */
@@ -326,6 +328,8 @@ public class BevelBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The color.
+   * 
    * @see java.awt.Component#getBackground()
    * @see java.awt.Color#brighter()
    */
@@ -347,6 +351,8 @@ public class BevelBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The color.
+   * 
    * @see java.awt.Component#getBackground()
    * @see java.awt.Color#darker()
    */
@@ -367,6 +373,8 @@ public class BevelBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The color.
+   * 
    * @see #getShadowInnerColor(java.awt.Component)
    * @see java.awt.Color#darker()
    */
@@ -384,6 +392,8 @@ public class BevelBorder extends AbstractBorder
    * highlighted edges when painting the border, or <code>null</code>
    * if that color will be derived from the background of the enclosed
    * Component.
+   * 
+   * @return The color (possibly <code>null</code>).
    */
   public Color getHighlightOuterColor()
   {
@@ -396,6 +406,8 @@ public class BevelBorder extends AbstractBorder
    * highlighted edges when painting the border, or <code>null</code>
    * if that color will be derived from the background of the enclosed
    * Component.
+   * 
+   * @return The color (possibly <code>null</code>).
    */
   public Color getHighlightInnerColor()
   {
@@ -408,6 +420,8 @@ public class BevelBorder extends AbstractBorder
    * shadowed edges when painting the border, or <code>null</code> if
    * that color will be derived from the background of the enclosed
    * Component.
+   * 
+   * @return The color (possibly <code>null</code>).
    */
   public Color getShadowInnerColor()
   {
@@ -420,6 +434,8 @@ public class BevelBorder extends AbstractBorder
    * shadowed edges when painting the border, or <code>null</code> if
    * that color will be derived from the background of the enclosed
    * Component.
+   * 
+   * @return The color (possibly <code>null</code>).
    */
   public Color getShadowOuterColor()
   {
@@ -430,6 +446,8 @@ public class BevelBorder extends AbstractBorder
   /**
    * Returns the appearance of this border, which is either {@link
    * #RAISED} or {@link #LOWERED}.
+   * 
+   * @return The bevel type ({@link #RAISED} or {@link #LOWERED}).
    */
   public int getBevelType()
   {
diff --git a/javax/swing/border/CompoundBorder.java b/javax/swing/border/CompoundBorder.java
index 998a9bab3..a69c5e20a 100644
--- a/javax/swing/border/CompoundBorder.java
+++ b/javax/swing/border/CompoundBorder.java
@@ -224,6 +224,8 @@ public class CompoundBorder extends AbstractBorder
    * Returns the outside border, which is painted outside both the
    * bordered Component and the inside border. It is valid for the
    * result to be <code>null</code>.
+   * 
+   * @return The outside border (possibly <code>null</code>).
    */
   public Border getOutsideBorder()
   {
@@ -234,6 +236,8 @@ public class CompoundBorder extends AbstractBorder
    * Returns the inside border, which is painted between the bordered
    * Component and the outside border. It is valid for the result to
    * be <code>null</code>.
+   * 
+   * @return The inside border (possibly <code>null</code>).
    */
   public Border getInsideBorder ()
   {
diff --git a/javax/swing/border/EtchedBorder.java b/javax/swing/border/EtchedBorder.java
index 22882b78c..cd48b18da 100644
--- a/javax/swing/border/EtchedBorder.java
+++ b/javax/swing/border/EtchedBorder.java
@@ -281,6 +281,8 @@ public class EtchedBorder extends AbstractBorder
   /**
    * Returns the appearance of this EtchedBorder, which is either
    * {@link #RAISED} or {@link #LOWERED}.
+   * 
+   * @return The type ({@link #RAISED} or {@link #LOWERED}).
    */
   public int getEtchType()
   {
@@ -297,6 +299,8 @@ public class EtchedBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The color.
+   * 
    * @see java.awt.Component#getBackground()
    * @see java.awt.Color#brighter()
    */
@@ -312,6 +316,8 @@ public class EtchedBorder extends AbstractBorder
    * Returns the color that will be used for highlighted parts when
    * painting the border, or <code>null</code> if that color will be
    * derived from the background of the enclosed Component.
+   * 
+   * @return The highlight color (possibly <code>null</code>).
    */
   public Color getHighlightColor()
   {
@@ -328,6 +334,8 @@ public class EtchedBorder extends AbstractBorder
    *
    * @param c the component enclosed by this border.
    *
+   * @return The shadow color.
+   * 
    * @see java.awt.Component#getBackground()
    * @see java.awt.Color#darker()
    */
@@ -344,6 +352,8 @@ public class EtchedBorder extends AbstractBorder
    * Returns the color that will be used for shadowed parts when
    * painting the border, or <code>null</code> if that color will be
    * derived from the background of the enclosed Component.
+   * 
+   * @return The shadow color (possibly <code>null</code>).
    */
   public Color getShadowColor()
   {
diff --git a/javax/swing/border/LineBorder.java b/javax/swing/border/LineBorder.java
index 36abddd91..31e19fe1f 100644
--- a/javax/swing/border/LineBorder.java
+++ b/javax/swing/border/LineBorder.java
@@ -162,8 +162,10 @@ public class LineBorder extends AbstractBorder
   
   
   /**
-   * Returns a black, one pixel thick, plain LineBorder. The method
-   * may always return the same (singleton) LineBorder instance.
+   * Returns a black, one pixel thick, plain {@link LineBorder}. The method
+   * may always return the same (singleton) {@link LineBorder} instance.
+   * 
+   * @return The border.
    */
   public static Border createBlackLineBorder()
   {
@@ -178,8 +180,10 @@ public class LineBorder extends AbstractBorder
   
   
   /**
-   * Returns a gray, one pixel thick, plain LineBorder. The method
-   * may always return the same (singleton) LineBorder instance.
+   * Returns a gray, one pixel thick, plain {@link LineBorder}. The method
+   * may always return the same (singleton) {@link LineBorder} instance.
+   * 
+   * @return The border.
    */
   public static Border createGrayLineBorder()
   {
@@ -295,6 +299,8 @@ public class LineBorder extends AbstractBorder
   
   /**
    * Returns the color of the line.
+   * 
+   * @return The line color (never <code>null</code>).
    */
   public Color getLineColor()
   {
@@ -304,6 +310,8 @@ public class LineBorder extends AbstractBorder
   
   /**
    * Returns the thickness of the line in pixels.
+   * 
+   * @return The line thickness (in pixels).
    */
   public int getThickness()
   {
diff --git a/javax/swing/border/MatteBorder.java b/javax/swing/border/MatteBorder.java
index 4d5b8c253..114cac623 100644
--- a/javax/swing/border/MatteBorder.java
+++ b/javax/swing/border/MatteBorder.java
@@ -299,6 +299,8 @@ public class MatteBorder extends EmptyBorder
    * Returns the color that is used for filling the border, or
    * <code>null</code> if the border is filled with repetitions of a
    * tile icon.
+   * 
+   * @return The color (possibly <code>null</code>).
    */
   public Color getMatteColor()
   {
@@ -310,6 +312,8 @@ public class MatteBorder extends EmptyBorder
    * Returns the icon is used for tiling the border, or
    * <code>null</code> if the border is filled with a color instead of
    * an icon.
+   * 
+   * @return The icon (possibly <code>null</code>).
    */
   public Icon getTileIcon()
   {
diff --git a/javax/swing/border/TitledBorder.java b/javax/swing/border/TitledBorder.java
index 8d3ee13d4..38b575423 100644
--- a/javax/swing/border/TitledBorder.java
+++ b/javax/swing/border/TitledBorder.java
@@ -912,8 +912,10 @@ public class TitledBorder extends AbstractBorder
    * Calculates the minimum size needed for displaying the border
    * and its title.
    *
-   * @param c the Component for which this TitledBorder consitutes
+   * @param c the Component for which this TitledBorder constitutes
    *        a border.
+   *        
+   * @return The minimum size.
    */
   public Dimension getMinimumSize(Component c)
   {
@@ -980,6 +982,10 @@ public class TitledBorder extends AbstractBorder
   /**
    * Performs various measurements for the current state of this TitledBorder
    * and the given Component.
+   * 
+   * @param c  the component (<code>null</code> not permitted).
+   * 
+   * @return Various measurements.
    */
   private Measurements getMeasurements(Component c)
   {
@@ -1172,6 +1178,8 @@ public class TitledBorder extends AbstractBorder
     /**
      * Calculates the minimum size needed for displaying the border
      * and its title. Used by {@link TitledBorder#getMinimumSize(Component)}.
+     * 
+     * @return The minimum size.
      */
     public Dimension getMinimumSize()
     {