Index: java/awt/MediaTracker.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/awt/MediaTracker.java,v
retrieving revision 1.10
diff -u -r1.10 MediaTracker.java
--- java/awt/MediaTracker.java	8 Apr 2005 18:25:47 -0000	1.10
+++ java/awt/MediaTracker.java	11 Apr 2005 07:37:31 -0000
@@ -45,33 +45,86 @@
   * This class is used for keeping track of the status of various media
   * objects.
   *
+  * Media objects are tracked by assigning them an ID. It is possible
+  * to assign the same ID to mutliple objects, effectivly grouping them
+  * together. In this case the status flags (address@hidden #statusID}) and error flag
+  * (@link #isErrorID} and address@hidden #getErrorId}) are ORed together. This
+  * means that you cannot say exactly which media object has which status,
+  * at most you can say that there <em>are</em> certain media objects with
+  * some certain status.
+  * 
+  * At the moment only images are supported by this class.
+  *
   * @author Aaron M. Renn (address@hidden)
   * @author Bryce McKinlay
   */
 public class MediaTracker implements java.io.Serializable
 {
+  /** Indicates that the media is still loading. */
   public static final int LOADING = 1 << 0;
+
+  /** Indicates that the loading operation has been aborted. */
   public static final int ABORTED = 1 << 1;
+
+  /** Indicates that an error has occured during loading of the media. */
   public static final int ERRORED = 1 << 2;
+
+  /** Indicates that the media has been successfully and completely loaded. */
   public static final int COMPLETE = 1 << 3;
-  
+
+  /** The component on which the media is eventually been drawn. */
   Component target;
+
+  /** The head of the linked list of tracked media objects. */
   MediaEntry head;
 
+  /** Our serialVersionUID for serialization. */
   static final long serialVersionUID = -483174189758638095L;
 
+  /**
+   * This represents a media object that is tracked by a MediaTracker.
+   * It also implements a simple linked list.
+   */
   // FIXME: The serialized form documentation says MediaEntry is a 
   // serializable field, but the serialized form of MediaEntry itself
   // doesn't appear to be documented.
   class MediaEntry implements ImageObserver
   {
+    /** The ID of the media object. */
     int id;
+
+    /** The media object. (only images are supported ATM). */
     Image image;
+
+    /** The link to the next entry in the list. */
     MediaEntry next;
+
+    /** The tracking status. */
     int status;
+
+    /** The width of the image. */
     int width;
+
+    /** The height of the image. */
     int height;
     
+    /**
+     * Receives notification from an address@hidden java.awt.image.ImageProducer}
+     * that more data of the image is available.
+     *
+     * @param img the image that is updated
+     * @param flags flags from the ImageProducer that indicate the status
+     *        of the loading process
+     * @param x the X coordinate of the upper left corner of the image
+     * @param y the Y coordinate of the upper left corner of the image
+     * @param width the width of the image
+     * @param height the height of the image
+     *
+     * @return <code>true</code> if more data is needed, <code>false</code>
+     *         otherwise
+     *
+     * @see address@hidden java.awt.image.ImageObserver}
+     */
     public boolean imageUpdate(Image img, int flags, int x, int y, 
 			       int width, int height)
     {
@@ -96,11 +149,23 @@
     }
   }
 
+  /**
+   * Constructs a new MediaTracker for the component <code>c</code>. The
+   * component should be the component that uses the media (i.e. draws it).
+   *
+   * @param c the Component that wants to use the media
+   */
   public MediaTracker(Component c)
   {
     target = c;
   }
 
+  /**
+   * Adds an image to the tracker with the specified <code>ID</code>.
+   *
+   * @param image the image to be added
+   * @param id the ID of the tracker list to which the image is added
+   */
   public void addImage(Image image, int id)
   {
     MediaEntry e = new MediaEntry();
@@ -113,6 +178,16 @@
     e.imageUpdate(image, flags, -1, -1, -1, -1);
   }
 
+  /**
+   * Adds an image to the tracker with the specified <code>ID</code>.
+   * The image is expected to be rendered with the specified width and
+   * height.
+   *
+   * @param image the image to be added
+   * @param id the ID of the tracker list to which the image is added
+   * @param width the width of the image
+   * @param height the height of the image
+   */
   public void addImage(Image image, int id, int width, int height)
   {
     MediaEntry e = new MediaEntry();
@@ -127,11 +202,36 @@
     e.imageUpdate(image, flags, -1, -1, width, height);
   }
 
+  /**
+   * Checks if all media objects have finished loading, i.e. are
+   * address@hidden #COMPLETE}, address@hidden #ABORTED} or address@hidden #ERRORED}.
+   *
+   * If the media objects are not already loading, a call to this
+   * method does <em>not</em> start loading. This is equivalent to
+   * a call to <code>checkAll(false)</code>.
+   *
+   * @return if all media objects have finished loading either by beeing
+   *         complete, have been aborted or errored.
+   */
   public boolean checkAll()
   {
     return checkAll(false);
   }
 
+  /**
+   * Checks if all media objects have finished loading, i.e. are
+   * address@hidden #COMPLETE}, address@hidden #ABORTED} or address@hidden #ERRORED}.
+   *
+   * If the media objects are not already loading, and <code>load</code>
+   * is <code>true</code> then a call to this
+   * method starts loading the media objects.
+   *
+   * @param load if <code>true</code> this method starts loading objects
+   *        that are not already loading
+   *
+   * @return if all media objects have finished loading either by beeing
+   *         complete, have been aborted or errored.
+   */
   public boolean checkAll(boolean load)
   {
     MediaEntry e = head;
@@ -158,6 +258,14 @@
     return result;
   }
 
+  /**
+   * Checks if any of the registered media objects has encountered an error
+   * during loading.
+   *
+   * @return <code>true</code> if at least one media object has encountered
+   *         an error during loading, <code>false</code> otherwise
+   *
+   */
   public boolean isErrorAny()
   {
     MediaEntry e = head;    
@@ -170,6 +278,12 @@
     return false;
   }
 
+  /**
+   * Returns all media objects that have encountered errors during loading.
+   *
+   * @return an array of all media objects that have encountered errors
+   *         or <code>null</code> if there were no errors at all
+   */
   public Object[] getErrorsAny()
   {
     MediaEntry e = head;
@@ -190,6 +304,13 @@
       return result.toArray();
   }
 
+  /**
+   * Waits for all media objects to finish loading, either by completing
+   * successfully or by aborting or encountering an error.
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public void waitForAll() throws InterruptedException
   {
     synchronized (this)
@@ -199,6 +320,23 @@
     }
   }
 
+  /**
+   * Waits for all media objects to finish loading, either by completing
+   * successfully or by aborting or encountering an error.
+   *
+   * This method waits at most <code>ms</code> milliseconds. If the
+   * media objects have not completed loading within this timeframe, this
+   * method returns <code>false</code>, otherwise <code>true</code>.
+   *
+   * @param ms timeframe in milliseconds to wait for the media objects to
+   *        finish
+   *
+   * @return <code>true</code> if all media objects have successfully loaded
+   *         within the timeframe, <code>false</code> otherwise
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public boolean waitForAll(long ms) throws InterruptedException
   {
     long start = System.currentTimeMillis();
@@ -217,6 +355,16 @@
     return result;
   }
 
+  /**
+   * Returns the status flags of all registered media objects ORed together.
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return the status flags of all tracked media objects ORed together
+   */
   public int statusAll(boolean load)
   {
     int result = 0;
@@ -234,11 +382,31 @@
     return result;
   }
 
+  /**
+   * Checks if the media objects with <code>ID</code> have completed loading.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return <code>true</code> if all media objects with <code>ID</code>
+   *         have successfully finished
+   */
   public boolean checkID(int id)
   {
     return checkID(id, false);
   }
 
+  /**
+   * Checks if the media objects with <code>ID</code> have completed loading.
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param id the ID of the media objects to check
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return <code>true</code> if all media objects with <code>ID</code>
+   *         have successfully finished
+   */
   public boolean checkID(int id, boolean load)
   {
     MediaEntry e = head;
@@ -265,6 +433,15 @@
     return result;
   }
 
+  /**
+   * Returns <code>true</code> if any of the media objects with <code>ID</code>
+   * have encountered errors during loading, false otherwise.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return <code>true</code> if any of the media objects with <code>ID</code>
+   *         have encountered errors during loading, false otherwise
+   */
   public boolean isErrorID(int id)
   {
     MediaEntry e = head;    
@@ -277,6 +454,15 @@
     return false;
   }
 
+  /**
+   * Returns all media objects with the specified ID that have encountered
+   * an error.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return an array of all media objects  with the specified ID that
+   *         have encountered an error
+   */
   public Object[] getErrorsID(int id)
   {
     MediaEntry e = head;
@@ -297,6 +483,15 @@
       return result.toArray();
   }
 
+  /**
+   * Waits for all media objects with the specified ID to finish loading,
+   * either by completing successfully or by aborting or encountering an error.
+   *
+   * @param id the ID of the media objects to wait for
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public void waitForID(int id) throws InterruptedException
   {
     MediaEntry e = head;
@@ -307,6 +502,24 @@
     }
   }
 
+  /**
+   * Waits for all media objects with the specified ID to finish loading,
+   * either by completing successfully or by aborting or encountering an error.
+   *
+   * This method waits at most <code>ms</code> milliseconds. If the
+   * media objects have not completed loading within this timeframe, this
+   * method returns <code>false</code>, otherwise <code>true</code>.
+   *
+   * @param id the ID of the media objects to wait for
+   * @param ms timeframe in milliseconds to wait for the media objects to
+   *        finish
+   *
+   * @return <code>true</code> if all media objects have successfully loaded
+   *         within the timeframe, <code>false</code> otherwise
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public boolean waitForID(int id, long ms) throws InterruptedException
   {
     MediaEntry e = head;
@@ -327,6 +540,18 @@
     return result;
   }
 
+  /**
+   * Returns the status flags of the media objects with the specified ID
+   * ORed together.
+   *
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return the status flags of all tracked media objects ORed together
+   */
   public int statusID(int id, boolean load)
   {
     int result = 0;
@@ -347,6 +572,11 @@
     return result;
   }
 
+  /**
+   * Removes an image from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image)
   {
     MediaEntry e = head;
@@ -365,6 +595,11 @@
       }
   }
 
+  /**
+   * Removes an image with the specified ID from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image, int id)
   {
     MediaEntry e = head;
@@ -384,6 +619,11 @@
       }  
   }
 
+  /**
+   * Removes an image with the specified ID and scale from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image, int id, int width, int height)
   {
     MediaEntry e = head;