[cp-patches] FYI: FileSystemView, UnixFileSystemView

[David Gilbert]

I committed this patch to fill out the API docs for these classes:

2005-11-02  David Gilbert  <address@hidden>

        * javax/swing/filechooser/FileSystemView.java: Added API docs all over,
        * javax/swing/filechooser/UnixFileSystemView.java: Likewise.

Regards,

Dave

Index: javax/swing/filechooser/FileSystemView.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/filechooser/FileSystemView.java,v
retrieving revision 1.9
diff -u -r1.9 FileSystemView.java
--- javax/swing/filechooser/FileSystemView.java 11 Oct 2005 09:30:16 -0000      
1.9
+++ javax/swing/filechooser/FileSystemView.java 2 Nov 2005 10:25:11 -0000
@@ -40,11 +40,14 @@
 import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
+
 import javax.swing.Icon;
+import javax.swing.JFileChooser;
 
 
 /**
- * DOCUMENT ME!
+ * The base class providing a view of the file system for use by the 
+ * address@hidden JFileChooser} component.
  */
 public abstract class FileSystemView
 {
@@ -52,12 +55,12 @@
   private static FileSystemView defaultFileSystemView;
   
   /**
-   * DOCUMENT ME!
+   * Creates a new file object with the given name in the specified directory.
    *
-   * @param dir DOCUMENT ME!
-   * @param filename DOCUMENT ME!
+   * @param dir  the directory (<code>null</code> permitted).
+   * @param filename  the file name.
    *
-   * @return DOCUMENT ME!
+   * @return A new file object.
    */
   public File createFileObject(File dir, String filename)
   {
@@ -65,11 +68,11 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a new file object from the specified path.
    *
-   * @param path DOCUMENT ME!
+   * @param path  the path.
    *
-   * @return DOCUMENT ME!
+   * @return A new file object.
    */
   public File createFileObject(String path)
   {
@@ -92,13 +95,16 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Creates a new folder with a unique name in the specified directory and
+   * returns a address@hidden File} object representing the new directory.
    *
-   * @param containingDir DOCUMENT ME!
+   * @param containingDir  the directory to contain the new folder 
+   *                       (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return A address@hidden File} object representing the new directory.
    *
-   * @throws IOException DOCUMENT ME!
+   * @throws IOException if an exception occurs while creating the new 
+   *                     directory.
    */
   public abstract File createNewFolder(File containingDir)
                                 throws IOException;
@@ -118,9 +124,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the default directory.
    *
-   * @return DOCUMENT ME!
+   * @return The default directory.
    */
   public File getDefaultDirectory()
   {
@@ -128,12 +134,16 @@
   }
 
   /**
-   * DOCUMENT ME!
-   *
-   * @param dir DOCUMENT ME!
-   * @param useFileHiding DOCUMENT ME!
+   * Returns an array containing the files in the given directory.  The 
+   * <code>useFileHiding</code> controls whether or not hidden files are 
+   * included in the result.
+   *
+   * @param dir  the directory (if <code>null</code>
+   * @param useFileHiding  a flag that controls whether or not hidden files are
+   *                       included in the result (pass in <code>true</code> to
+   *                       exclude hidden files).
    *
-   * @return DOCUMENT ME!
+   * @return The files in the given directory (possibly <code>null</code>).
    */
   public File[] getFiles(File dir, boolean useFileHiding)
   {
@@ -161,6 +171,7 @@
       {
         if (File.separator.equals("/"))
           defaultFileSystemView = new UnixFileSystemView();
+        // FIXME: need to implement additional views
         // else if (File.Separator.equals("\"))
         //   return new Win32FileSystemView();
         // else 
@@ -170,9 +181,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the home directory for the current user.
    *
-   * @return DOCUMENT ME!
+   * @return The home directory for the current user.
    */
   public File getHomeDirectory()
   {
@@ -180,11 +191,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the parent directory for the given file/directory.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file/directory.
    *
-   * @return DOCUMENT ME!
+   * @return The parent directory (or <code>null</code> if there is no parent
+   *         directory).
    */
   public File getParentDirectory(File f)
   {
@@ -194,9 +206,14 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns an array containing the file system roots.  On Unix-like 
platforms,
+   * this array will contain just a single item ("/"), while other platforms
+   * may return multiple roots.
+   * <p>
+   * This method is implemented to return <code>null</code>, subclasses must
+   * override this method.
    *
-   * @return DOCUMENT ME!
+   * @return An array containing the file system roots.
    */
   public File[] getRoots()
   {
@@ -205,11 +222,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the name of a file as it would be displayed by the underlying 
+   * system.  This implementation returns <code>null</code>, subclasses must
+   * override.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public String getSystemDisplayName(File f)
   {
@@ -217,11 +236,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the icon that would be displayed for the given file by the 
+   * underlying system.  This implementation returns <code>null</code>, 
+   * subclasses must override.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public Icon getSystemIcon(File f)
   {
@@ -229,11 +250,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the type description of a file that would be displayed by the 
+   * underlying system.  This implementation returns <code>null</code>, 
+   * subclasses must override.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public String getSystemTypeDescription(File f)
   {
@@ -253,11 +276,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if the given directory represents a disk 
+   * drive, and <code>false</code> otherwise.  This default implementation
+   * always returns <code>false</code>.
    *
-   * @param dir DOCUMENT ME!
+   * @param dir  the directory.
    *
-   * @return DOCUMENT ME!
+   * @return <code>false</code>.
    */
   public boolean isDrive(File dir)
   {
@@ -265,11 +290,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if <code>f</code> is a file or directory, and
+   * <code>false</code> otherwise.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file/directory.
    *
-   * @return DOCUMENT ME!
+   * @return <code>true</code> if <code>f</code> is a file or directory, and
+   * <code>false</code> otherwise.
    */
   public boolean isFileSystem(File f)
   {
@@ -277,11 +304,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if the given directory is a file system root,
+   * and <code>false</code> otherwise.
    *
-   * @param dir DOCUMENT ME!
+   * @param dir  the directory.
    *
-   * @return DOCUMENT ME!
+   * @return <code>true</code> if the given directory is a file system root,
+   *          and <code>false</code> otherwise.
    */
   public boolean isFileSystemRoot(File dir)
   {
@@ -296,11 +325,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if the given directory represents a floppy 
+   * drive, and <code>false</code> otherwise.  This default implementation
+   * always returns <code>false</code>.
    *
-   * @param dir DOCUMENT ME!
+   * @param dir  the directory.
    *
-   * @return DOCUMENT ME!
+   * @return <code>false</code>.
    */
   public boolean isFloppyDrive(File dir)
   {
@@ -308,11 +339,13 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if the given file is hidden, and 
+   * <code>false</code> otherwise.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>true</code> if the given file is hidden, and 
+   *         <code>false</code> otherwise.
    */
   public boolean isHiddenFile(File f)
   {
@@ -320,12 +353,14 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if <code>folder</code> is the parent of 
+   * <code>file</code>, and <code>false</code> otherwise.
    *
-   * @param folder DOCUMENT ME!
-   * @param file DOCUMENT ME!
+   * @param folder  the folder (<code>null</code> not permitted).
+   * @param file  the file (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return <code>true</code> if <code>folder</code> is the parent of 
+   *         <code>file</code>, and <code>false</code> otherwise.
    */
   public boolean isParent(File folder, File file)
   {
@@ -349,11 +384,14 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns <code>true</code> if the file is traversable, and 
+   * <code>false</code> otherwise.  Here, all directories are considered
+   * traversable, and files are considered non-traversable. 
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file or directory (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return <code>true</code> if the file is traversable, and 
+   *         <code>false</code> otherwise.
    */
   public Boolean isTraversable(File f)
   {
Index: javax/swing/filechooser/UnixFileSystemView.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/filechooser/UnixFileSystemView.java,v
retrieving revision 1.2
diff -u -r1.2 UnixFileSystemView.java
--- javax/swing/filechooser/UnixFileSystemView.java     2 Jul 2005 20:32:50 
-0000       1.2
+++ javax/swing/filechooser/UnixFileSystemView.java     2 Nov 2005 10:25:12 
-0000
@@ -43,21 +43,31 @@
 
 
 /**
- * DOCUMENT ME!
+ * A concrete implementation of address@hidden FileSystemView} that is 
appropriate for
+ * Unix-like systems.
+ * 
+ * @see FileSystemView#getFileSystemView()
  */
 class UnixFileSystemView extends FileSystemView
 {
-  /** DOCUMENT ME! */
+  /** The default name for new folders. */
   private static final String NEW_FOLDER_NAME = "NewFolder";
 
   /**
-   * DOCUMENT ME!
+   * Creates a new folder with a unique name in the specified directory and
+   * returns a address@hidden File} object representing the new directory.  
The name 
+   * of the new folder is <code>NewFolder</code> or, if a directory or file 
+   * with that name already exists, <code>NewFolder.n</code> where 
+   * <code>n</code> is the lowest integer greater than zero that results in 
+   * a unique directory name.
    *
-   * @param containingDir DOCUMENT ME!
+   * @param containingDir  the directory to contain the new folder 
+   *                       (<code>null</code> not permitted).
    *
-   * @return DOCUMENT ME!
+   * @return A address@hidden File} object representing the new directory.
    *
-   * @throws IOException DOCUMENT ME!
+   * @throws IOException if an exception occurs while creating the new 
+   *                     directory.
    */
   public File createNewFolder(File containingDir) throws IOException
   {
@@ -82,9 +92,9 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns an array containing the file system root. 
    *
-   * @return DOCUMENT ME!
+   * @return An array containing the file system root.
    */
   public File[] getRoots()
   {
@@ -92,11 +102,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the name of a file as it would be displayed by the underlying 
+   * system.  This method is NOT YET IMPLEMENTED.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public String getSystemDisplayName(File f)
   {
@@ -105,11 +116,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the icon that would be displayed for the given file by the 
+   * underlying system.  This method is NOT YET IMPLEMENTED.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public Icon getSystemIcon(File f)
   {
@@ -118,11 +130,12 @@
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the description of a file that would be displayed by the 
+   * underlying system.  This method is NOT YET IMPLEMENTED.
    *
-   * @param f DOCUMENT ME!
+   * @param f  the file.
    *
-   * @return DOCUMENT ME!
+   * @return <code>null</code>.
    */
   public String getSystemTypeDescription(File f)
   {