<Swing Dev> Review Request for 8039966: fix doclint block tag issues in swing filechooser and colorchooser classes

[sergey malenkov]

Hello,

      /**
       * The icon that represents this file in the <code>JFileChooser</code>.
+     *
+     * @param f a {@code File} object
+     * @return an {@code Icon} to be displayed by the file chooser
       */
      public Icon getIcon(File f) {

What if the FileView class is used from another component, not the file 
chooser.
I prefer something like this: an {@code Icon} that represent the 
specified {@code File}.

      /**
       * 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
       */
      public File[] getRoots() {

It is obvious that this method returns an array of File objects.
It is better to specify these objects. For example:

+ * @return an array of File objects which represent root partitions of 
this file system.

      /**
       * Returns a File object constructed in dir from the given filename.
+     * If {@code dir} is {@code null}, then the new {@code File} instance is
+     * created as if by invoking the single-argument {@code File} constructor
+     * on the given {@code filename} string.
+     *
+     * @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) {

Seems this javadoc describes an implementation details.
We should specify here that the created File object represents a file 
with specified filename, that is located in specified folder.

etc...


Note that all such changes in the API require an approval from CCC.
This is not a small typo. You really change the *public* API!

Thanks
SAM

On 18.04.2014 2:57, Steve Sides wrote:
> Hello,
>
> Could you please review the fix for the following bug:
> https://bugs.openjdk.java.net/browse/JDK-8039966
>
> Webrev corresponding:
> http://cr.openjdk.java.net/~ssides/8039966/8039966.4/
>
> This addresses missing @parm and @return block tags in javadoc for 
> javax/swing/colorchooser and filechooser classes as noted by doclint.
>
> It does not address methods which are missing javadoc comments 
> completely.
>
> You may want to check the wording of @param for 
> (un)installChooserPanel(). The original seemed a little incorrect to me.
>
> thanks,
>
> -steve
>