[cp-patches] FYI: BasicFileChooserUI.java API docs

[David Gilbert]

I committed this patch:

2005-10-04  David Gilbert  <address@hidden>

        * javax/swing/plaf/basic/BasicFileChooserUI.java: Added API docs all
        over.

Regards,

Dave

Index: javax/swing/plaf/basic/BasicFileChooserUI.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/plaf/basic/BasicFileChooserUI.java,v
retrieving revision 1.12
diff -u -r1.12 BasicFileChooserUI.java
--- javax/swing/plaf/basic/BasicFileChooserUI.java      15 Sep 2005 17:54:39 
-0000      1.12
+++ javax/swing/plaf/basic/BasicFileChooserUI.java      4 Oct 2005 20:55:28 
-0000
@@ -48,7 +48,6 @@
 import java.awt.Polygon;
 import java.awt.Window;
 import java.awt.event.ActionEvent;
-import java.awt.event.ActionListener;
 import java.awt.event.ItemEvent;
 import java.awt.event.ItemListener;
 import java.awt.event.MouseAdapter;
@@ -60,9 +59,9 @@
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Hashtable;
+
 import javax.swing.AbstractAction;
 import javax.swing.Action;
-import javax.swing.BoxLayout;
 import javax.swing.ButtonGroup;
 import javax.swing.Icon;
 import javax.swing.JButton;
@@ -92,25 +91,30 @@
 
 
 /**
- * DOCUMENT ME!
+ * A UI delegate for the address@hidden JFileChooser} component under the 
+ * address@hidden BasicLookAndFeel}.
  */
 public class BasicFileChooserUI extends FileChooserUI
 {
   /**
-   * DOCUMENT ME!
+   * A file filter that accepts all files.
    */
   protected class AcceptAllFileFilter extends FileFilter
   {
+    /**
+     * Creates a new instance.
+     */
     public AcceptAllFileFilter()
     {
     }
     
     /**
-     * DOCUMENT ME!
+     * Returns <code>true</code> always, as all files are accepted by this
+     * filter.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file.
      *
-     * @return DOCUMENT ME!
+     * @return Always <code>true</code>.
      */
     public boolean accept(File f)
     {
@@ -118,9 +122,9 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns a description for this filter.
      *
-     * @return DOCUMENT ME!
+     * @return A description for the file filter.
      */
     public String getDescription()
     {
@@ -129,7 +133,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Handles a user action to approve the dialog selection.
+   * 
+   * @see BasicFileChooserUI#getApproveSelectionAction()
    */
   protected class ApproveSelectionAction extends AbstractAction
   {
@@ -141,10 +147,9 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the current selection and closes the dialog.
      * 
-     * @param e
-     *          DOCUMENT ME!
+     * @param e  the action event.
      */
     public void actionPerformed(ActionEvent e)
     {
@@ -167,22 +172,25 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Provides presentation information about files and directories.
    */
   protected class BasicFileView extends FileView
   {
-    /** DOCUMENT ME! */
+    /** Storage for cached icons. */
     protected Hashtable iconCache = new Hashtable();
 
+    /**
+     * Creates a new instance.
+     */
     public BasicFileView()
     {
     }
 
     /**
-     * DOCUMENT ME!
+     * Adds an icon to the cache, associating it with the given file/directory.
      *
-     * @param f DOCUMENT ME!
-     * @param i DOCUMENT ME!
+     * @param f  the file/directory.
+     * @param i  the icon.
      */
     public void cacheIcon(File f, Icon i)
     {
@@ -190,7 +198,7 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Clears the icon cache.
      */
     public void clearIconCache()
     {
@@ -198,11 +206,12 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Retrieves the icon associated with the specified file/directory, if 
+     * there is one.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return The cached icon (or <code>null</code>).
      */
     public Icon getCachedIcon(File f)
     {
@@ -210,11 +219,13 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns a description of the given file/directory.  In this 
+     * implementation, the description is the same as the name returned by 
+     * address@hidden #getName(File)}.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return A description of the given file/directory.
      */
     public String getDescription(File f)
     {
@@ -222,11 +233,11 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns an icon appropriate for the given file or directory.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return An icon.
      */
     public Icon getIcon(File f)
     {
@@ -242,11 +253,11 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns the name for the given file/directory.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return The name of the file/directory.
      */
     public String getName(File f)
     {
@@ -254,11 +265,11 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns a localised description for the type of file/directory.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return A type description for the given file/directory.
      */
     public String getTypeDescription(File f)
     {
@@ -269,11 +280,12 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Returns address@hidden Boolean#TRUE} if the given file/directory is 
hidden,
+     * and address@hidden Boolean#FALSE} otherwise.
      *
-     * @param f DOCUMENT ME!
+     * @param f  the file/directory.
      *
-     * @return DOCUMENT ME!
+     * @return address@hidden Boolean#TRUE} or address@hidden Boolean#FALSE}.
      */
     public Boolean isHidden(File f)
     {
@@ -282,21 +294,23 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Handles an action to cancel the file chooser.
+   * 
+   * @see BasicFileChooserUI#getCancelSelectionAction()
    */
   protected class CancelSelectionAction extends AbstractAction
   {
     /**
-     * Creates a new CancelSelectionAction object.
+     * Creates a new <code>CancelSelectionAction</code> object.
      */
     protected CancelSelectionAction()
     {
     }
 
     /**
-     * DOCUMENT ME!
+     * Cancels the selection and closes the dialog.
      *
-     * @param e DOCUMENT ME!
+     * @param e  the action event (ignored).
      */
     public void actionPerformed(ActionEvent e)
     {
@@ -306,21 +320,24 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * An action to handle changes to the parent directory (for example, via
+   * a click on the "up folder" button).
+   * 
+   * @see BasicFileChooserUI#getChangeToParentDirectoryAction()
    */
   protected class ChangeToParentDirectoryAction extends AbstractAction
   {
     /**
-     * Creates a new ChangeToParentDirectoryAction object.
+     * Creates a new <code>ChangeToParentDirectoryAction</code> object.
      */
     protected ChangeToParentDirectoryAction()
     {
     }
 
     /**
-     * DOCUMENT ME!
+     * Handles the action event.
      *
-     * @param e DOCUMENT ME!
+     * @param e  the action event.
      */
     public void actionPerformed(ActionEvent e)
     {
@@ -331,11 +348,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * A mouse listener that handles double-click events.
+   * 
+   * @see BasicFileChooserUI#createDoubleClickListener(JFileChooser, JList)
    */
   protected class DoubleClickListener extends MouseAdapter
   {
-    /** DOCUMENT ME! */
+    /** A timer. */
     private Timer timer = null;
 
     /** DOCUMENT ME! */
@@ -359,10 +378,9 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Handles a mouse click event.
      * 
-     * @param e
-     *          DOCUMENT ME!
+     * @param e  the event.
      */
     public void mouseClicked(MouseEvent e)
     {
@@ -408,10 +426,9 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * Handles a mouse entered event (NOT IMPLEMENTED).
      * 
-     * @param e
-     *          DOCUMENT ME!
+     * @param e  the mouse event.
      */
     public void mouseEntered(MouseEvent e)
     {
@@ -420,21 +437,25 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * An action that changes the file chooser to display the user's home 
+   * directory. 
+   * 
+   * @see BasicFileChooserUI#getGoHomeAction()
    */
   protected class GoHomeAction extends AbstractAction
   {
     /**
-     * Creates a new GoHomeAction object.
+     * Creates a new <code>GoHomeAction</code> object.
      */
     protected GoHomeAction()
     {
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the directory to the user's home directory, and repaints the
+     * file chooser component.
      *
-     * @param e DOCUMENT ME!
+     * @param e  the action event (ignored).
      */
     public void actionPerformed(ActionEvent e)
     {
@@ -446,21 +467,23 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * An action that handles the creation of a new folder/directory.
+   * 
+   * @see BasicFileChooserUI#getNewFolderAction()
    */
   protected class NewFolderAction extends AbstractAction
   {
     /**
-     * Creates a new NewFolderAction object.
+     * Creates a new <code>NewFolderAction</code> object.
      */
     protected NewFolderAction()
     {
     }
 
     /**
-     * DOCUMENT ME!
+     * Handles the event by creating a new folder.
      *
-     * @param e DOCUMENT ME!
+     * @param e  the action event (ignored).
      */
     public void actionPerformed(ActionEvent e)
     {
@@ -479,12 +502,14 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * A listener for selection events in the file list.
+   * 
+   * @see BasicFileChooserUI#createListSelectionListener(JFileChooser)
    */
   protected class SelectionListener implements ListSelectionListener
   {
     /**
-     * Creates a new SelectionListener object.
+     * Creates a new <code>SelectionListener</code> object.
      */
     protected SelectionListener()
     {
@@ -510,6 +535,8 @@
 
   /**
    * DOCUMENT ME!
+   * 
+   * @see BasicFileChooserUI#getUpdateAction()
    */
   protected class UpdateAction extends AbstractAction
   {
@@ -521,25 +548,26 @@
     }
 
     /**
-     * DOCUMENT ME!
+     * NOT YET IMPLEMENTED.
      *
-     * @param e DOCUMENT ME!
+     * @param e  the action event.
      */
     public void actionPerformed(ActionEvent e)
     {
+      // FIXME: implement this
     }
   }
 
-  /** DOCUMENT ME! */
+  /** The localised mnemonic for the cancel button. */
   protected int cancelButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the cancel button. */
   protected String cancelButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the cancel button. */
   protected String cancelButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** An icon representing a computer. */
   protected Icon computerIcon = new Icon()
     {
       public int getIconHeight()
@@ -554,10 +582,11 @@
 
       public void paintIcon(Component c, Graphics g, int x, int y)
       {
+        // FIXME: is this not implemented, or is the icon intentionally blank?
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon for the "details view" button. */
   protected Icon detailsViewIcon = new Icon()
     {
       public int getIconHeight()
@@ -586,7 +615,7 @@
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon representing a directory. */
   protected Icon directoryIcon = new Icon()
     {
       public int getIconHeight()
@@ -625,16 +654,16 @@
       }
     };
 
-  /** DOCUMENT ME! */
+  /** The localised Mnemonic for the open button. */
   protected int directoryOpenButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the open button. */
   protected String directoryOpenButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the open button. */
   protected String directoryOpenButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** An icon representing a file. */
   protected Icon fileIcon = new Icon()
     {
       public int getIconHeight()
@@ -674,7 +703,7 @@
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon representing a floppy drive. */
   protected Icon floppyDriveIcon = new Icon()
     {
       public int getIconHeight()
@@ -689,10 +718,11 @@
 
       public void paintIcon(Component c, Graphics g, int x, int y)
       {
+        // FIXME: is this not implemented, or is the icon intentionally blank?
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon representing a hard drive. */
   protected Icon hardDriveIcon = new Icon()
     {
       public int getIconHeight()
@@ -707,19 +737,20 @@
 
       public void paintIcon(Component c, Graphics g, int x, int y)
       {
+        // FIXME: is this not implemented, or is the icon intentionally blank?
       }
     };
 
-  /** DOCUMENT ME! */
+  /** The localised mnemonic for the "help" button. */
   protected int helpButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the "help" button. */
   protected String helpButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the help button. */
   protected String helpButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** An icon representing the user's home folder. */
   protected Icon homeFolderIcon = new Icon()
     {
       public int getIconHeight()
@@ -759,7 +790,7 @@
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon for the "list view" button. */
   protected Icon listViewIcon = new Icon()
     {
       public int getIconHeight()
@@ -801,37 +832,37 @@
       }
     };
 
-  /** DOCUMENT ME! */
+  /** An icon for the "new folder" button. */
   protected Icon newFolderIcon = directoryIcon;
 
-  /** DOCUMENT ME! */
+  /** The localised mnemonic for the "open" button. */
   protected int openButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the "open" button. */
   protected String openButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the "open" button. */
   protected String openButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** The localised mnemonic for the "save" button. */
   protected int saveButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the "save" button. */
   protected String saveButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the save button. */
   protected String saveButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** The localised mnemonic for the "update" button. */
   protected int updateButtonMnemonic;
 
-  /** DOCUMENT ME! */
+  /** The localised text for the "update" button. */
   protected String updateButtonText;
 
-  /** DOCUMENT ME! */
+  /** The localised tool tip text for the "update" button. */
   protected String updateButtonToolTipText;
 
-  /** DOCUMENT ME! */
+  /** An icon for the "up folder" button. */
   protected Icon upFolderIcon = new Icon()
     {
       public int getIconHeight()
@@ -882,71 +913,74 @@
 
   // -- begin private, but package local since used in inner classes --
 
+  /** The file chooser component represented by this UI delegate. */
   JFileChooser filechooser;
 
-  /** DOCUMENT ME! */
+  /** The file list. */
   JList filelist;
 
-  /** DOCUMENT ME! */
+  /** The combo box used to display/select file filters. */
   JComboBox filters;
 
-  /** DOCUMENT ME! */
+  /** The model for the directory list. */
   BasicDirectoryModel model;
 
-  /** DOCUMENT ME! */
+  /** The file filter for all files. */
   FileFilter acceptAll = new AcceptAllFileFilter();
 
-  /** DOCUMENT ME! */
+  /** The default file view. */
   FileView fv = new BasicFileView();
 
-  /** DOCUMENT ME! */
+  /** The icon size. */
   static final int ICON_SIZE = 24;
 
-  /** DOCUMENT ME! */
+  /** A combo box for display/selection of parent directories. */
   JComboBox parents;
 
-  /** DOCUMENT ME! */
+  /** The current file name. */
   String filename;
 
-  /** DOCUMENT ME! */
+  /** The accept (open/save) button. */
   JButton accept;
 
-  /** DOCUMENT ME! */
+  /** The cancel button. */
   JButton cancel;
 
-  /** DOCUMENT ME! */
+  /** The button to move up to the parent directory. */
   JButton upFolderButton;
 
-  /** DOCUMENT ME! */
+  /** The button to create a new directory. */
   JButton newFolderButton;
 
-  /** DOCUMENT ME! */
+  /** The button to move to the user's home directory. */
   JButton homeFolderButton;
 
-  /** DOCUMENT ME! */
+  /** An optional accessory panel. */
   JPanel accessoryPanel;
 
-  /** DOCUMENT ME! */
+  /** A property change listener. */
   PropertyChangeListener propertyChangeListener;
 
-  /** DOCUMENT ME! */
+  /** The text describing the filter for "all files". */
   String acceptAllFileFilterText;
 
-  /** DOCUMENT ME! */
+  /** The text describing a directory type. */
   String dirDescText;
 
-  /** DOCUMENT ME! */
+  /** The text describing a file type. */
   String fileDescText;
 
-  /** DOCUMENT ME! */
+  /** Is a directory selected? */
   boolean dirSelected = false;
 
-  /** DOCUMENT ME! */
+  /** The current directory. */
   File currDir = null;
 
+  // FIXME: describe what is contained in the bottom panel
+  /** The bottom panel. */
   JPanel bottomPanel;
   
-  /** DOCUMENT ME! */
+  /** The close panel. */
   JPanel closePanel;
 
   /** Text box that displays file name */
@@ -997,6 +1031,9 @@
     }
   }
 
+  /**
+   * Closes the dialog.
+   */
   void closeDialog()
   {
     Window owner = SwingUtilities.windowForComponent(filechooser);
@@ -1005,9 +1042,9 @@
   }
 
   /**
-   * Creates a new BasicFileChooserUI object.
+   * Creates a new <code>BasicFileChooserUI</code> object.
    *
-   * @param b DOCUMENT ME!
+   * @param b  the file chooser component.
    */
   public BasicFileChooserUI(JFileChooser b)
   {
@@ -1015,11 +1052,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns a UI delegate for the given component.
    *
-   * @param c DOCUMENT ME!
+   * @param c  the component (should be a address@hidden JFileChooser}).
    *
-   * @return DOCUMENT ME!
+   * @return A new UI delegate.
    */
   public static ComponentUI createUI(JComponent c)
   {
@@ -1027,10 +1064,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Installs the UI for the specified component.
    * 
-   * @param c
-   *          DOCUMENT ME!
+   * @param c  the component (should be a address@hidden JFileChooser}).
    */
   public void installUI(JComponent c)
   {
@@ -1051,10 +1087,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls this UI from the given component.
    * 
-   * @param c
-   *          DOCUMENT ME!
+   * @param c  the component (should be a address@hidden JFileChooser}).
    */
   public void uninstallUI(JComponent c)
   {
@@ -1161,9 +1196,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and install the subcomponents for the file chooser.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   public void installComponents(JFileChooser fc)
   {
@@ -1285,9 +1320,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls the components from the file chooser.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   public void uninstallComponents(JFileChooser fc)
   {
@@ -1303,9 +1338,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Installs the listeners required by this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void installListeners(JFileChooser fc)
   {
@@ -1325,9 +1360,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls the listeners previously installed by this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void uninstallListeners(JFileChooser fc)
   {
@@ -1336,9 +1371,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Installs the defaults for this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void installDefaults(JFileChooser fc)
   {
@@ -1347,9 +1382,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls the defaults previously added by this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void uninstallDefaults(JFileChooser fc)
   {
@@ -1358,9 +1393,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Installs the icons for this UI delegate (NOT YET IMPLEMENTED).
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void installIcons(JFileChooser fc)
   {
@@ -1368,9 +1403,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls the icons previously added by this UI delegate (NOT YET
+   * IMPLEMENTED).
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void uninstallIcons(JFileChooser fc)
   {
@@ -1378,9 +1414,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Installs the strings used by this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void installStrings(JFileChooser fc)
   {
@@ -1408,9 +1444,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Uninstalls the strings previously added by this UI delegate.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   protected void uninstallStrings(JFileChooser fc)
   {
@@ -1436,7 +1472,7 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a new directory model.
    */
   protected void createModel()
   {
@@ -1444,9 +1480,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the directory model.
    *
-   * @return DOCUMENT ME!
+   * @return The directory model.
    */
   public BasicDirectoryModel getModel()
   {
@@ -1454,11 +1490,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a listener to handle changes to the properties of the given
+   * file chooser component.
    * 
-   * @param fc
-   *          DOCUMENT ME!
-   * @return DOCUMENT ME!
+   * @param fc  the file chooser component.
+   * 
+   * @return A new listener.
    */
   public PropertyChangeListener createPropertyChangeListener(JFileChooser fc)
   {
@@ -1575,9 +1612,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the current file name.
    * 
-   * @return DOCUMENT ME!
+   * @return The current file name.
    */
   public String getFileName()
   {
@@ -1585,9 +1622,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the current directory name.
    *
-   * @return DOCUMENT ME!
+   * @return The directory name.
+   * 
+   * @see #setDirectoryName(String)
    */
   public String getDirectoryName()
   {
@@ -1596,9 +1635,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Sets the file name.
    *
-   * @param filename DOCUMENT ME!
+   * @param filename  the file name.
+   * 
+   * @see #getFileName()
    */
   public void setFileName(String filename)
   {
@@ -1606,9 +1647,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Sets the directory name (NOT IMPLEMENTED).
    *
-   * @param dirname DOCUMENT ME!
+   * @param dirname  the directory name.
+   * 
+   * @see #getDirectoryName()
    */
   public void setDirectoryName(String dirname)
   {
@@ -1616,9 +1659,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Rescans the current directory.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    */
   public void rescanCurrentDirectory(JFileChooser fc)
   {
@@ -1627,10 +1670,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * NOT YET IMPLEMENTED.
    *
-   * @param fc DOCUMENT ME!
-   * @param f DOCUMENT ME!
+   * @param fc  the file chooser.
+   * @param f  the file.
    */
   public void ensureFileIsVisible(JFileChooser fc, File f)
   {
@@ -1638,9 +1681,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the address@hidden JFileChooser} component that this UI delegate 
+   * represents.
    *
-   * @return DOCUMENT ME!
+   * @return The component represented by this UI delegate.
    */
   public JFileChooser getFileChooser()
   {
@@ -1648,9 +1692,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the optional accessory panel.
    *
-   * @return DOCUMENT ME!
+   * @return The optional accessory panel.
    */
   public JPanel getAccessoryPanel()
   {
@@ -1658,11 +1702,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns an approve (open or save) button for the dialog.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    *
-   * @return DOCUMENT ME!
+   * @return The button.
    */
   public JButton getApproveButton(JFileChooser fc)
   {
@@ -1673,11 +1717,14 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the tool tip text for the approve (open/save) button.  This first
+   * checks the file chooser to see if a value has been explicitly set - if
+   * not, a default value appropriate for the type of file chooser is 
+   * returned.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser.
    *
-   * @return DOCUMENT ME!
+   * @return The tool tip text.
    */
   public String getApproveButtonToolTipText(JFileChooser fc)
   {
@@ -1690,7 +1737,7 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Clears the icon cache.
    */
   public void clearIconCache()
   {
@@ -1699,11 +1746,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a new listener to handle selections in the file list.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser component.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden SelectionListener}.
    */
   public ListSelectionListener createListSelectionListener(JFileChooser fc)
   {
@@ -1711,12 +1758,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a new listener to handle double-click events.
    *
-   * @param fc DOCUMENT ME!
-   * @param list DOCUMENT ME!
+   * @param fc  the file chooser component.
+   * @param list  the list.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden DoubleClickListener}.
    */
   protected MouseListener createDoubleClickListener(JFileChooser fc, JList 
list)
   {
@@ -1724,9 +1771,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if a directory is selected, and 
+   * <code>false</code> otherwise.
    *
-   * @return DOCUMENT ME!
+   * @return A boolean.
    */
   protected boolean isDirectorySelected()
   {
@@ -1734,9 +1782,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Sets the flag that indicates whether the current directory is selected.
    *
-   * @param selected DOCUMENT ME!
+   * @param selected  the new flag value.
    */
   protected void setDirectorySelected(boolean selected)
   {
@@ -1744,9 +1792,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the current directory.
    *
-   * @return DOCUMENT ME!
+   * @return The current directory.
    */
   protected File getDirectory()
   {
@@ -1754,9 +1802,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Sets the current directory.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the directory.
    */
   protected void setDirectory(File f)
   {
@@ -1764,11 +1812,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the "accept all" file filter.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser component.
    *
-   * @return DOCUMENT ME!
+   * @return The "accept all" file filter.
    */
   public FileFilter getAcceptAllFileFilter(JFileChooser fc)
   {
@@ -1776,11 +1824,15 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the file view for the file chooser.  This returns either the
+   * file view that has been explicitly set for the address@hidden 
JFileChooser}, or
+   * a default file view.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser component.
    *
-   * @return DOCUMENT ME!
+   * @return The file view.
+   * 
+   * @see JFileChooser#getFileView()
    */
   public FileView getFileView(JFileChooser fc)
   {
@@ -1790,11 +1842,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the dialog title.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return The dialog title.
+   * 
+   * @see JFileChooser#getDialogTitle()
    */
   public String getDialogTitle(JFileChooser fc)
   {
@@ -1819,11 +1873,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the approve button mnemonic.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return The approve button mnemonic.
+   * 
+   * @see JFileChooser#getApproveButtonMnemonic()
    */
   public int getApproveButtonMnemonic(JFileChooser fc)
   {
@@ -1836,11 +1892,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the approve button text.
    *
-   * @param fc DOCUMENT ME!
+   * @param fc  the file chooser (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return The approve button text.
+   * 
+   * @see JFileChooser#getApproveButtonText()
    */
   public String getApproveButtonText(JFileChooser fc)
   {
@@ -1853,9 +1911,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new action that will be used with the "new folder" 
+   * button.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden GoHomeAction}.
    */
   public Action getNewFolderAction()
   {
@@ -1863,9 +1922,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new action that will be used with the "home folder" 
+   * button.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden GoHomeAction}.
    */
   public Action getGoHomeAction()
   {
@@ -1873,9 +1933,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new action that will be used with the "up folder" 
+   * button.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden ChangeToParentDirectoryAction}.
    */
   public Action getChangeToParentDirectoryAction()
   {
@@ -1883,9 +1944,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new action that will be used with the "approve" 
+   * button.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden ApproveSelectionAction}.
    */
   public Action getApproveSelectionAction()
   {
@@ -1893,9 +1955,10 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new action that will be used with the "cancel" 
+   * button.
    *
-   * @return DOCUMENT ME!
+   * @return A new instance of address@hidden CancelSelectionAction}.
    */
   public Action getCancelSelectionAction()
   {
@@ -1903,9 +1966,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates and returns a new instance of address@hidden UpdateAction}.
    *
-   * @return DOCUMENT ME!
+   * @return An action. 
    */
   public Action getUpdateAction()
   {