8039966: Add @return and @param block tags in colorchooser and filechooser swing classes

Reviewed-by: malenkov, alexsch

jdk/src/share/classes/javax/swing/colorchooser/AbstractColorChooserPanel.java

@@ -145,7 +145,8 @@ public abstract class AbstractColorChooserPanel extends JPanel {
     /**
      * Invoked when the panel is added to the chooser.
      * If you override this, be sure to call <code>super</code>.
-     * @param enclosingChooser  the panel to be added
+     *
+     * @param enclosingChooser the chooser to which the panel is to be added
      * @exception RuntimeException  if the chooser panel has already been
      *                          installed
      */
@@ -163,6 +164,8 @@ public abstract class AbstractColorChooserPanel extends JPanel {
     /**
      * Invoked when the panel is removed from the chooser.
      * If override this, be sure to call <code>super</code>.
+     *
+     * @param enclosingChooser the chooser from which the panel is to be removed
      */
   public void uninstallChooserPanel(JColorChooser enclosingChooser) {
         chooser.removePropertyChangeListener("enabled", enabledListener);

jdk/src/share/classes/javax/swing/filechooser/FileFilter.java

@@ -51,11 +51,16 @@ import java.io.File;
 public abstract class FileFilter {
     /**
      * Whether the given file is accepted by this filter.
+     *
+     * @param f the File to test
+     * @return true if the file is to be accepted
      */
     public abstract boolean accept(File f);
 
     /**
      * The description of this filter. For example: "JPG and GIF Images"
+     *
+     * @return the description of this filter
      * @see FileView#getName
      */
     public abstract String getDescription();

jdk/src/share/classes/javax/swing/filechooser/FileSystemView.java

@@ -324,11 +324,18 @@ public abstract class FileSystemView {
 
     /**
      * Creates a new folder with a default folder name.
+     *
+     * @param containingDir a {@code File} object denoting directory to contain the new folder
+     * @return a {@code File} object denoting the newly created folder
+     * @throws IOException if new folder could not be created
      */
     public abstract File createNewFolder(File containingDir) throws IOException;
 
     /**
      * Returns whether a file is hidden or not.
+     *
+     * @param f a {@code File} object
+     * @return true if the given {@code File} denotes a hidden file
      */
     public boolean isHiddenFile(File f) {
         return f.isHidden();
@@ -395,6 +402,9 @@ public abstract class FileSystemView {
      * Returns all root partitions on this system. For example, on
      * Windows, this would be the "Desktop" folder, while on DOS this
      * would be the A: through Z: drives.
+     *
+     * @return an array of {@code File} objects representing all root partitions
+     *         on this system
      */
     public File[] getRoots() {
         // Don't cache this array, because filesystem might change
@@ -435,6 +445,10 @@ public abstract class FileSystemView {
 
     /**
      * Returns a File object constructed in dir from the given filename.
+     *
+     * @param dir an abstract pathname denoting a directory
+     * @param filename a {@code String} representation of a pathname
+     * @return a {@code File} object created from {@code dir} and {@code filename}
      */
     public File createFileObject(File dir, String filename) {
         if(dir == null) {
@@ -446,6 +460,9 @@ public abstract class FileSystemView {
 
     /**
      * Returns a File object constructed from the given path string.
+     *
+     * @param path {@code String} representation of path
+     * @return a {@code File} object created from the given {@code path}
      */
     public File createFileObject(String path) {
         File f = new File(path);
@@ -458,6 +475,12 @@ public abstract class FileSystemView {
 
     /**
      * Gets the list of shown (i.e. not hidden) files.
+     *
+     * @param dir the root directory of files to be returned
+     * @param useFileHiding determine if hidden files are returned
+     * @return an array of {@code File} objects representing files and
+     *         directories in the given {@code dir}. It includes hidden
+     *         files if {@code useFileHiding} is false.
      */
     public File[] getFiles(File dir, boolean useFileHiding) {
         List<File> files = new ArrayList<File>();

jdk/src/share/classes/javax/swing/filechooser/FileView.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -69,6 +69,9 @@ public abstract class FileView {
     /**
      * The name of the file. Normally this would be simply
      * <code>f.getName()</code>.
+     *
+     * @param f a {@code File} object
+     * @return a {@code String} representing the name of the file
      */
     public String getName(File f) {
         return null;
@@ -78,6 +81,11 @@ public abstract class FileView {
      * A human readable description of the file. For example,
      * a file named <i>jag.jpg</i> might have a description that read:
      * "A JPEG image file of James Gosling's face".
+     *
+     * @param f a {@code File} object
+     * @return a {@code String} containing a description of the file or
+     *         {@code null} if it is not available.
+     *
      */
     public String getDescription(File f) {
         return null;
@@ -87,6 +95,10 @@ public abstract class FileView {
      * A human readable description of the type of the file. For
      * example, a <code>jpg</code> file might have a type description of:
      * "A JPEG Compressed Image File"
+     *
+     * @param f a {@code File} object
+     * @return a {@code String} containing a description of the type of the file
+     *         or {@code null} if it is not available   .
      */
     public String getTypeDescription(File f) {
         return null;
@@ -94,6 +106,10 @@ public abstract class FileView {
 
     /**
      * The icon that represents this file in the <code>JFileChooser</code>.
+     *
+     * @param f a {@code File} object
+     * @return an {@code Icon} which represents the specified {@code File} or
+     *         {@code null} if it is not available.
      */
     public Icon getIcon(File f) {
         return null;
@@ -103,6 +119,12 @@ public abstract class FileView {
      * Whether the directory is traversable or not. This might be
      * useful, for example, if you want a directory to represent
      * a compound document and don't want the user to descend into it.
+     *
+     * @param f a {@code File} object representing a directory
+     * @return {@code true} if the directory is traversable,
+     *         {@code false} if it is not, and {@code null} if the
+     *         file system should be checked.
+     * @see FileSystemView#isTraversable
      */
     public Boolean isTraversable(File f) {
         return null;