2004-09-08 Sven de Marothy <sven@physto.se>

	Patch from David Gilbert <david.gilbert@object-refinery.com>:
	*java/awt/AWTEventMulticaster.java:
	Fix a big number of documentation errors.
	*java/awt/Adjustable.java
	*java/awt/Point.java
	*java/awt/Polygon.java
	*java/awt/Rectangle.java
	*java/awt/Shape.java
	*java/awt/geom/Area.java
	*java/awt/geom/Ellipse2D.java
	*java/awt/geom/PathIterator.java
	*java/awt/geom/Point2D.java
	*java/awt/geom/Rectangle2D.java
	*java/lang/Comparable.java
	*java/util/Arrays.java:
	Likewise. Thank you David!

14 files changed, 201 insertions, 106 deletions

diff --git a/ChangeLog b/ChangeLog
index 70e001a5a..c68e5d9ac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,24 @@
+2004-09-08  Sven de Marothy  <sven@physto.se>
+	
+	Patch from David Gilbert <david.gilbert@object-refinery.com>:
+	*java/awt/AWTEventMulticaster.java:
+	Fix a big number of documentation errors.
+	*java/awt/Adjustable.java
+	*java/awt/Point.java
+	*java/awt/Polygon.java
+	*java/awt/Rectangle.java
+	*java/awt/Shape.java
+	*java/awt/geom/Area.java
+	*java/awt/geom/Ellipse2D.java
+	*java/awt/geom/PathIterator.java 
+	*java/awt/geom/Point2D.java
+	*java/awt/geom/Rectangle2D.java 
+	*java/lang/Comparable.java
+	*java/util/Arrays.java:
+	Likewise. Thank you David!
+
 2004-09-07  Sven de Marothy  <sven@physto.se>
+
 	* java/awt/geom/doc-files/Area-1.png:
 	Graphics for Area documentation. New file.
 
diff --git a/java/awt/AWTEventMulticaster.java b/java/awt/AWTEventMulticaster.java
index 58950ef0b..b26d1f35d 100644
--- a/java/awt/AWTEventMulticaster.java
+++ b/java/awt/AWTEventMulticaster.java
@@ -181,7 +181,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentResized(ComponentEvent e)
   {
@@ -193,7 +193,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentMoved(ComponentEvent e)
   {
@@ -205,7 +205,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentShown(ComponentEvent e)
   {
@@ -217,7 +217,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentHidden(ComponentEvent e)
   {
@@ -229,7 +229,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentAdded(ContainerEvent e)
   {
@@ -241,7 +241,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void componentRemoved(ContainerEvent e)
   {
@@ -253,7 +253,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void focusGained(FocusEvent e)
   {
@@ -265,7 +265,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void focusLost(FocusEvent e)
   {
@@ -277,7 +277,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void keyTyped(KeyEvent e)
   {
@@ -289,7 +289,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void keyPressed(KeyEvent e)
   {
@@ -301,7 +301,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void keyReleased(KeyEvent e)
   {
@@ -313,7 +313,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseClicked(MouseEvent e)
   {
@@ -325,7 +325,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mousePressed(MouseEvent e)
   {
@@ -337,7 +337,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseReleased(MouseEvent e)
   {
@@ -349,7 +349,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseEntered(MouseEvent e)
   {
@@ -361,7 +361,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseExited(MouseEvent e)
   {
@@ -373,7 +373,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseDragged(MouseEvent e)
   {
@@ -385,7 +385,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void mouseMoved(MouseEvent e)
   {
@@ -397,7 +397,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowOpened(WindowEvent e)
   {
@@ -409,7 +409,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowClosing(WindowEvent e)
   {
@@ -421,7 +421,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowClosed(WindowEvent e)
   {
@@ -433,7 +433,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowIconified(WindowEvent e)
   {
@@ -445,7 +445,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowDeiconified(WindowEvent e)
   {
@@ -457,7 +457,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowActivated(WindowEvent e)
   {
@@ -469,7 +469,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void windowDeactivated(WindowEvent e)
   {
@@ -481,7 +481,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.4
    */
   public void windowStateChanged(WindowEvent e)
@@ -494,7 +494,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.4
    */
   public void windowGainedFocus(WindowEvent e)
@@ -507,7 +507,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.4
    */
   public void windowLostFocus(WindowEvent e)
@@ -520,7 +520,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void actionPerformed(ActionEvent e)
   {
@@ -532,7 +532,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void itemStateChanged(ItemEvent e)
   {
@@ -544,7 +544,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void adjustmentValueChanged(AdjustmentEvent e)
   {
@@ -556,7 +556,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    */
   public void textValueChanged(TextEvent e)
   {
@@ -568,7 +568,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.2
    */
   public void inputMethodTextChanged(InputMethodEvent e)
@@ -581,7 +581,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.2
    */
   public void caretPositionChanged(InputMethodEvent e)
@@ -594,7 +594,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.3
    */
   public void hierarchyChanged(HierarchyEvent e)
@@ -607,7 +607,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.3
    */
   public void ancestorMoved(HierarchyEvent e)
@@ -620,7 +620,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.3
    */
   public void ancestorResized(HierarchyEvent e)
@@ -633,7 +633,7 @@ public class AWTEventMulticaster
    * Handles this event by dispatching it to the "a" and "b" listener
    * instances.
    *
-   * @param event the event to handle
+   * @param e the event to handle
    * @since 1.4
    */
   public void mouseWheelMoved(MouseWheelEvent e)
diff --git a/java/awt/Adjustable.java b/java/awt/Adjustable.java
index 58116e4e5..815c77ca9 100644
--- a/java/awt/Adjustable.java
+++ b/java/awt/Adjustable.java
@@ -157,7 +157,7 @@ public interface Adjustable
    * Adds a listener that will receive adjustment events for this object.
    *
    * @param listener the adjustment listener to add
-   * @see AdjustmentEvent
+   * @see java.awt.event.AdjustmentEvent
    */
   void addAdjustmentListener(AdjustmentListener listener);
 
@@ -165,7 +165,7 @@ public interface Adjustable
    * Removes an adjustment listener from this object.
    *
    * @param listener the adjustment listener to remove
-   * @see AdjustmentEvent
+   * @see java.awt.event.AdjustmentEvent
    */
   void removeAdjustmentListener(AdjustmentListener listener);
 } // interface Adjustable
diff --git a/java/awt/Point.java b/java/awt/Point.java
index 9d5126434..3731b4134 100644
--- a/java/awt/Point.java
+++ b/java/awt/Point.java
@@ -95,7 +95,7 @@ public class Point extends Point2D implements Serializable
    * Initializes a new instance of <code>Point</code> with coordinates
    * identical to the coordinates of the specified points.
    *
-   * @param point the point to copy the coordinates from
+   * @param p the point to copy the coordinates from
    * @throws NullPointerException if p is null
    */
   public Point(Point p)
diff --git a/java/awt/Polygon.java b/java/awt/Polygon.java
index 96c370aaf..36739e306 100644
--- a/java/awt/Polygon.java
+++ b/java/awt/Polygon.java
@@ -684,7 +684,7 @@ public class Polygon implements Shape, Serializable
    * path iterator is not either.
    *
    * @param transform an optional transform to apply to the iterator
-   * @param double the maximum distance for deviation from the real boundary
+   * @param flatness the maximum distance for deviation from the real boundary
    * @return a new iterator over the boundary
    * @since 1.2
    */
diff --git a/java/awt/Rectangle.java b/java/awt/Rectangle.java
index 5dc54116f..66190960a 100644
--- a/java/awt/Rectangle.java
+++ b/java/awt/Rectangle.java
@@ -338,7 +338,7 @@ public class Rectangle extends Rectangle2D implements Shape, Serializable
    * its upper left corner.
    *
    * @return the point where this rectangle is located
-   * @see setLocation(Point)
+   * @see #setLocation(Point)
    * @since 1.1
    */
   public Point getLocation()
diff --git a/java/awt/Shape.java b/java/awt/Shape.java
index 8d61c4a9a..47c97192a 100644
--- a/java/awt/Shape.java
+++ b/java/awt/Shape.java
@@ -57,8 +57,8 @@ import java.awt.geom.Rectangle2D;
  * @author Aaron M. Renn <arenn@urbanophile.com>
  * @see PathIterator
  * @see AffineTransform
- * @see FlatteningPathIterator
- * @see GeneralPath
+ * @see java.awt.geom.FlatteningPathIterator
+ * @see java.awt.geom.GeneralPath
  * @since 1.0
  * @status updated to 1.4
  */
@@ -109,15 +109,15 @@ public interface Shape
    * Test if a high-precision rectangle intersects the shape. This is true
    * if any point in the rectangle is in the shape, with the caveat that the
    * operation may include high probability estimates when the actual
-   * calculation is prohibitively expensive. The {@link Area} class can
-   * be used for more precise answers.
+   * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 
+   * class can be used for more precise answers.
    *
    * @param x the x coordinate of the rectangle
    * @param y the y coordinate of the rectangle
    * @param w the width of the rectangle, undefined results if negative
    * @param h the height of the rectangle, undefined results if negative
    * @return true if the rectangle intersects this shape
-   * @see Area
+   * @see java.awt.geom.Area
    * @since 1.2
    */
   boolean intersects(double x, double y, double w, double h);
@@ -126,8 +126,8 @@ public interface Shape
    * Test if a high-precision rectangle intersects the shape. This is true
    * if any point in the rectangle is in the shape, with the caveat that the
    * operation may include high probability estimates when the actual
-   * calculation is prohibitively expensive. The {@link Area} class can
-   * be used for more precise answers.
+   * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 
+   * class can be used for more precise answers.
    *
    * @param r the rectangle
    * @return true if the rectangle intersects this shape
@@ -141,15 +141,15 @@ public interface Shape
    * Test if a high-precision rectangle lies completely in the shape. This is
    * true if all points in the rectangle are in the shape, with the caveat
    * that the operation may include high probability estimates when the actual
-   * calculation is prohibitively expensive. The {@link Area} class can
-   * be used for more precise answers.
+   * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 
+   * class can be used for more precise answers.
    *
    * @param x the x coordinate of the rectangle
    * @param y the y coordinate of the rectangle
    * @param w the width of the rectangle, undefined results if negative
    * @param h the height of the rectangle, undefined results if negative
    * @return true if the rectangle is contained in this shape
-   * @see Area
+   * @see java.awt.geom.Area
    * @since 1.2
    */
   boolean contains(double x, double y, double w, double h);
@@ -158,8 +158,8 @@ public interface Shape
    * Test if a high-precision rectangle lies completely in the shape. This is
    * true if all points in the rectangle are in the shape, with the caveat
    * that the operation may include high probability estimates when the actual
-   * calculation is prohibitively expensive. The {@link Area} class can
-   * be used for more precise answers.
+   * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 
+   * class can be used for more precise answers.
    *
    * @param r the rectangle
    * @return true if the rectangle is contained in this shape
@@ -195,7 +195,7 @@ public interface Shape
    * iterations from future changes to the boundary, and document this fact.
    *
    * @param transform an optional transform to apply to the iterator
-   * @param double the maximum distance for deviation from the real boundary
+   * @param flatness the maximum distance for deviation from the real boundary
    * @return a new iterator over the boundary
    * @since 1.2
    */
diff --git a/java/awt/geom/Area.java b/java/awt/geom/Area.java
index 0b971048a..705699567 100644
--- a/java/awt/geom/Area.java
+++ b/java/awt/geom/Area.java
@@ -124,6 +124,10 @@ public class Area implements Shape, Cloneable
    * of non-self-intersecting subpaths, and any inner paths which
    * are found redundant in accordance with the Shape's winding rule
    * will not be included.
+   * 
+   * @param s  the shape (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>s</code> is <code>null</code>.
    */
   public Area(Shape s)
   {
@@ -261,7 +265,8 @@ public class Area implements Shape, Cloneable
 
   /**
    * Performs a subtraction operation on this Area.<BR>
-   * @param area - the area to be subtracted from this area.
+   * @param area the area to be subtracted from this area.
+   * @throws NullPointerException if <code>area</code> is <code>null</code>.
    */
   public void subtract(Area area)
   {
@@ -357,6 +362,7 @@ public class Area implements Shape, Cloneable
   /**
    * Performs an intersection operation on this Area.<BR>
    * @param area - the area to be intersected with this area.
+   * @throws NullPointerException if <code>area</code> is <code>null</code>.
    */
   public void intersect(Area area)
   {
@@ -448,6 +454,7 @@ public class Area implements Shape, Cloneable
   /**
    * Performs an exclusive-or operation on this Area.<BR>
    * @param area - the area to be XORed with this area.
+   * @throws NullPointerException if <code>area</code> is <code>null</code>.
    */
   public void exclusiveOr(Area area)
   {
@@ -666,6 +673,8 @@ public class Area implements Shape, Cloneable
   /**
    * Returns the bounds of this object in Rectangle format.
    * Please note that this may lead to loss of precision.
+   * 
+   * @return The bounds.
    * @see #getBounds2D()
    */
   public Rectangle getBounds()
@@ -698,8 +707,11 @@ public class Area implements Shape, Cloneable
 
   /**
    * Compares two Areas.
-   *
-   * @return true if the areas are equal. False otherwise.
+   * 
+   * @param area  the area to compare against this area (<code>null</code>
+   *              permitted).
+   * @return <code>true</code> if the areas are equal, and <code>false</code>
+   *         otherwise.
    */
   public boolean equals(Area area)
   {
@@ -742,7 +754,9 @@ public class Area implements Shape, Cloneable
   }
 
   /**
-   * Transforms this area by the AffineTransform at
+   * Transforms this area by the AffineTransform at.
+   * 
+   * @param at  the transform.
    */
   public void transform(AffineTransform at)
   {
@@ -761,8 +775,10 @@ public class Area implements Shape, Cloneable
 
   /**
    * Returns a new Area equal to this one, transformed
-   * by the AffineTransform at
+   * by the AffineTransform at.
+   * @param at  the transform.
    * @return the transformed area
+   * @throws NullPointerException if <code>at</code> is <code>null</code>.
    */
   public Area createTransformedArea(AffineTransform at)
   {
@@ -774,6 +790,8 @@ public class Area implements Shape, Cloneable
   /**
    * Determines if the point (x,y) is contained within this Area.
    *
+   * @param x the x-coordinate of the point.
+   * @param y the y-coordinate of the point.
    * @return true if the point is contained, false otherwise.
    */
   public boolean contains(double x, double y)
@@ -793,7 +811,10 @@ public class Area implements Shape, Cloneable
   /**
    * Determines if the Point2D p is contained within this Area.
    *
-   * @return true if the point is contained, false otherwise.
+   * @param p the point.
+   * @return <code>true</code> if the point is contained, <code>false</code> 
+   *         otherwise.
+   * @throws NullPointerException if <code>p</code> is <code>null</code>.
    */
   public boolean contains(Point2D p)
   {
@@ -807,7 +828,12 @@ public class Area implements Shape, Cloneable
    *
    * This method should always produce the correct results, unlike for other
    * classes in geom.
-   * @return true if the rectangle is considered contained
+   * 
+   * @param x the x-coordinate of the rectangle.
+   * @param y the y-coordinate of the rectangle.
+   * @param w the width of the the rectangle.
+   * @param h the height of the rectangle.
+   * @return <code>true</code> if the rectangle is considered contained
    */
   public boolean contains(double x, double y, double w, double h)
   {
@@ -859,7 +885,7 @@ public class Area implements Shape, Cloneable
     Rectangle2D r = new Rectangle2D.Double(x, y, w, h);
     for (int path = 0; path < holes.size(); path++)
       if (! ((Segment) holes.elementAt(path)).isSegmentOutside(r))
-	return false;
+        return false;
 
     return true;
   }
@@ -870,7 +896,11 @@ public class Area implements Shape, Cloneable
    *
    * This method should always produce the correct results, unlike for other
    * classes in geom.
-   * @return true if the rectangle is considered contained
+   * 
+   * @param r the rectangle.
+   * @return <code>true</code> if the rectangle is considered contained
+   * 
+   * @throws NullPointerException if <code>r</code> is <code>null</code>.
    */
   public boolean contains(Rectangle2D r)
   {
@@ -880,7 +910,13 @@ public class Area implements Shape, Cloneable
   /**
    * Determines if the rectangle specified by (x,y) as the upper-left
    * and with width w and height h intersects any part of this Area.
-   * @return true if the rectangle intersects the area, false otherwise.
+   * 
+   * @param x  the x-coordinate for the rectangle.
+   * @param y  the y-coordinate for the rectangle.
+   * @param w  the width of the rectangle.
+   * @param h  the height of the rectangle.
+   * @return <code>true</code> if the rectangle intersects the area, 
+   *         <code>false</code> otherwise.
    */
   public boolean intersects(double x, double y, double w, double h)
   {
@@ -938,7 +974,11 @@ public class Area implements Shape, Cloneable
   /**
    * Determines if the Rectangle2D specified by r intersects any
    * part of this Area.
-   * @return true if the rectangle intersects the area, false otherwise.
+   * @param r  the rectangle to test intersection with (<code>null</code>
+   *           not permitted).
+   * @return <code>true</code> if the rectangle intersects the area, 
+   *         <code>false</code> otherwise.
+   * @throws NullPointerException if <code>r</code> is <code>null</code>.
    */
   public boolean intersects(Rectangle2D r)
   {
@@ -948,24 +988,31 @@ public class Area implements Shape, Cloneable
   /**
    * Returns a PathIterator object defining the contour of this Area,
    * transformed by at.
+   * 
+   * @param at  the transform.
+   * @return A path iterator.
    */
   public PathIterator getPathIterator(AffineTransform at)
   {
     return (new AreaIterator(at));
   }
 
-  //---------------------------------------------------------------------
-  // Non-public methods and classes 
-
   /**
    * Returns a flattened PathIterator object defining the contour of this
    * Area, transformed by at and with a defined flatness.
+   * 
+   * @param at  the transform.
+   * @param flatness the flatness.
+   * @return A path iterator.
    */
   public PathIterator getPathIterator(AffineTransform at, double flatness)
   {
     return new FlatteningPathIterator(getPathIterator(at), flatness);
   }
 
+  //---------------------------------------------------------------------
+  // Non-public methods and classes 
+
   /**
    * Private pathiterator object.
    */
diff --git a/java/awt/geom/Ellipse2D.java b/java/awt/geom/Ellipse2D.java
index 209a2184b..bd64adf1e 100644
--- a/java/awt/geom/Ellipse2D.java
+++ b/java/awt/geom/Ellipse2D.java
@@ -101,6 +101,9 @@ public abstract class Ellipse2D extends RectangularShape
    * Note: An ellipse cannot be represented exactly in PathIterator
    * segments, the outline is thefore approximated with cubic
    * Bezier segments.
+   * 
+   * @param at an optional transform.
+   * @return A path iterator.
    */
   public PathIterator getPathIterator(AffineTransform at)
   {
@@ -139,6 +142,10 @@ public abstract class Ellipse2D extends RectangularShape
     return false;
   }
 
+  /**
+   * An {@link Ellipse2D} that stores its coordinates using <code>double</code>
+   * primitives.
+   */
   public static class Double extends Ellipse2D
   {
     /**
@@ -162,7 +169,7 @@ public abstract class Ellipse2D extends RectangularShape
     public double y;
 
     /**
-     * Creates a new Ellipse2D with an upper-right coordinate of (0,0)
+     * Creates a new Ellipse2D with an upper-left coordinate of (0,0)
      * and a zero size.
      */
     public Double()
@@ -172,11 +179,10 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Creates a new Ellipse2D within a given rectangle
      * using double-precision coordinates.<P>
-     * @param x - x coordinate of the upper-right of the bounding rectangle
-     * @param y - y coordinate of the upper-right of the bounding rectangle
+     * @param x - x coordinate of the upper-left of the bounding rectangle
+     * @param y - y coordinate of the upper-left of the bounding rectangle
      * @param w - width of the ellipse
      * @param h - height of the ellipse
-     *
      */
     public Double(double x, double y, double w, double h)
     {
@@ -188,6 +194,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the bounding-box of the ellipse.
+     * @return The bounding box.
      */
     public Rectangle2D getBounds2D()
     {
@@ -196,6 +203,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the height of the ellipse.
+     * @return The height of the ellipse.
      */
     public double getHeight()
     {
@@ -204,6 +212,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the width of the ellipse.
+     * @return The width of the ellipse.
      */
     public double getWidth()
     {
@@ -213,6 +222,7 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Returns x coordinate of the upper-left corner of
      * the ellipse's bounding-box.
+     * @return The x coordinate.
      */
     public double getX()
     {
@@ -222,6 +232,7 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Returns y coordinate of the upper-left corner of
      * the ellipse's bounding-box.
+     * @return The y coordinate.
      */
     public double getY()
     {
@@ -229,7 +240,10 @@ public abstract class Ellipse2D extends RectangularShape
     }
 
     /**
-     * Returns true if the ellipse encloses any area.
+     * Returns <code>true</code> if the ellipse encloses no area, and
+     * <code>false</code> otherwise.
+     * 
+     * @return A boolean.
      */
     public boolean isEmpty()
     {
@@ -239,8 +253,8 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Sets the geometry of the ellipse's bounding box.<P>
      *
-     * @param x - x coordinate of the upper-right of the bounding rectangle
-     * @param y - y coordinate of the upper-right of the bounding rectangle
+     * @param x - x coordinate of the upper-left of the bounding rectangle
+     * @param y - y coordinate of the upper-left of the bounding rectangle
      * @param w - width of the ellipse
      * @param h - height of the ellipse
      */
@@ -253,6 +267,10 @@ public abstract class Ellipse2D extends RectangularShape
     }
   } // class Double
 
+  /**
+   * An {@link Ellipse2D} that stores its coordinates using <code>float</code>
+   * primitives.
+   */
   public static class Float extends Ellipse2D
   {
     /**
@@ -276,7 +294,7 @@ public abstract class Ellipse2D extends RectangularShape
     public float y;
 
     /**
-     * Creates a new Ellipse2D with an upper-right coordinate of (0,0)
+     * Creates a new Ellipse2D with an upper-left coordinate of (0,0)
      * and a zero size.
      */
     public Float()
@@ -286,8 +304,8 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Creates a new Ellipse2D within a given rectangle
      * using floating-point precision.<P>
-     * @param x - x coordinate of the upper-right of the bounding rectangle
-     * @param y - y coordinate of the upper-right of the bounding rectangle
+     * @param x - x coordinate of the upper-left of the bounding rectangle
+     * @param y - y coordinate of the upper-left of the bounding rectangle
      * @param w - width of the ellipse
      * @param h - height of the ellipse
      *
@@ -302,6 +320,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the bounding-box of the ellipse.
+     * @return The bounding box.
      */
     public Rectangle2D getBounds2D()
     {
@@ -310,6 +329,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the height of the ellipse.
+     * @return The height of the ellipse.
      */
     public double getHeight()
     {
@@ -318,6 +338,7 @@ public abstract class Ellipse2D extends RectangularShape
 
     /**
      * Returns the width of the ellipse.
+     * @return The width of the ellipse.
      */
     public double getWidth()
     {
@@ -327,6 +348,7 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Returns x coordinate of the upper-left corner of
      * the ellipse's bounding-box.
+     * @return The x coordinate.
      */
     public double getX()
     {
@@ -336,6 +358,7 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Returns y coordinate of the upper-left corner of
      * the ellipse's bounding-box.
+     * @return The y coordinate.
      */
     public double getY()
     {
@@ -343,7 +366,10 @@ public abstract class Ellipse2D extends RectangularShape
     }
 
     /**
-     * Returns true if the ellipse encloses any area.
+     * Returns <code>true</code> if the ellipse encloses no area, and
+     * <code>false</code> otherwise.
+     * 
+     * @return A boolean.
      */
     public boolean isEmpty()
     {
@@ -353,8 +379,8 @@ public abstract class Ellipse2D extends RectangularShape
     /**
      * Sets the geometry of the ellipse's bounding box.<P>
      *
-     * @param x - x coordinate of the upper-right of the bounding rectangle
-     * @param y - y coordinate of the upper-right of the bounding rectangle
+     * @param x - x coordinate of the upper-left of the bounding rectangle
+     * @param y - y coordinate of the upper-left of the bounding rectangle
      * @param w - width of the ellipse
      * @param h - height of the ellipse
      */
@@ -371,8 +397,8 @@ public abstract class Ellipse2D extends RectangularShape
      *
      * Note: This leads to a loss of precision.<P>
      *
-     * @param x - x coordinate of the upper-right of the bounding rectangle
-     * @param y - y coordinate of the upper-right of the bounding rectangle
+     * @param x - x coordinate of the upper-left of the bounding rectangle
+     * @param y - y coordinate of the upper-left of the bounding rectangle
      * @param w - width of the ellipse
      * @param h - height of the ellipse
      */
diff --git a/java/awt/geom/PathIterator.java b/java/awt/geom/PathIterator.java
index 1fb0a46e0..8076b5c83 100644
--- a/java/awt/geom/PathIterator.java
+++ b/java/awt/geom/PathIterator.java
@@ -46,8 +46,8 @@ package java.awt.geom;
  *
  * @author Tom Tromey <tromey@cygnus.com>
  * @author Eric Blake <ebb9@email.byu.edu>
- * @see Shape
- * @see Stroke
+ * @see java.awt.Shape
+ * @see java.awt.Stroke
  * @see FlatteningPathIterator
  * @since 1.2
  * @status updated to 1.4
diff --git a/java/awt/geom/Point2D.java b/java/awt/geom/Point2D.java
index 48b12f67d..32c2e3d18 100644
--- a/java/awt/geom/Point2D.java
+++ b/java/awt/geom/Point2D.java
@@ -52,7 +52,7 @@ public abstract class Point2D implements Cloneable
   /**
    * The default constructor.
    *
-   * @see Point
+   * @see java.awt.Point
    * @see Point2D.Float
    * @see Point2D.Double
    */
diff --git a/java/awt/geom/Rectangle2D.java b/java/awt/geom/Rectangle2D.java
index 8203ca344..96baf336a 100644
--- a/java/awt/geom/Rectangle2D.java
+++ b/java/awt/geom/Rectangle2D.java
@@ -368,7 +368,7 @@ public abstract class Rectangle2D extends RectangularShape
    *
    * @param r the rectangle to add to this rectangle
    * @throws NullPointerException if r is null
-   * @see #union(Rectangle2D)
+   * @see #union(Rectangle2D, Rectangle2D, Rectangle2D)
    */
   public void add(Rectangle2D r)
   {
diff --git a/java/lang/Comparable.java b/java/lang/Comparable.java
index 96d4d6ac5..bfe72dbcb 100644
--- a/java/lang/Comparable.java
+++ b/java/lang/Comparable.java
@@ -52,18 +52,19 @@ package java.lang;
  *
  * <p>Lists, arrays, and sets of objects that implement this interface can
  * be sorted automatically, without the need for an explicit
- * {@link Comparator}. Note that <code>e1.compareTo(null)</code> should
- * throw an Exception; as should comparison between incompatible classes.
+ * {@link java.util.Comparator}. Note that <code>e1.compareTo(null)</code> 
+ * should throw an Exception; as should comparison between incompatible 
+ * classes.
  *
  * @author Geoff Berry
  * @author Warren Levy <warrenl@cygnus.com>
- * @see Comparator
- * @see Collections#sort(List)
- * @see Arrays#sort(Object[])
- * @see SortedSet
- * @see SortedMap
- * @see TreeSet
- * @see TreeMap
+ * @see java.util.Comparator
+ * @see java.util.Collections#sort(java.util.List)
+ * @see java.util.Arrays#sort(Object[])
+ * @see java.util.SortedSet
+ * @see java.util.SortedMap
+ * @see java.util.TreeSet
+ * @see java.util.TreeMap
  * @since 1.2
  * @status updated to 1.4
  */
diff --git a/java/util/Arrays.java b/java/util/Arrays.java
index e34901a23..f2337aee6 100644
--- a/java/util/Arrays.java
+++ b/java/util/Arrays.java
@@ -1021,7 +1021,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -1185,7 +1185,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -1349,7 +1349,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -1525,7 +1525,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -1701,7 +1701,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -1867,7 +1867,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -2037,7 +2037,7 @@ public class Arrays
   /**
    * Performs a recursive modified quicksort.
    *
-   * @param a the array to sort
+   * @param array the array to sort
    * @param from the start index (inclusive)
    * @param count the number of elements to sort
    */
@@ -2418,6 +2418,7 @@ public class Arrays
      * with the supplied element.
      *
      * @param index The index at which to place the new object.
+     * @param element The new object.
      * @return The object replaced by this operation.
      */
     public Object set(int index, Object element)
@@ -2489,7 +2490,7 @@ public class Arrays
      * is shrunk or enlarged to the size of the
      * internal array, and filled with its objects.
      *
-     * @param The array to fill with the objects in this list.
+     * @param array The array to fill with the objects in this list.
      * @return The array containing the objects in this list,
      *         which may or may not be == to array.
      */