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

[Steve Sides]

Hi Sergey, et. all,
changes as per comments: 
http://sqeweb.us.oracle.com/coretools/ssides/webrevs/8039966/8039966.5/

Some comments in line...

On 4/24/2014 5:16 AM, sergey malenkov wrote:
> 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}.
I see your point, although, this is in the 'filechooser' package and is 
documented as
"an abstract class that can be implemented to provide the filechooser 
with UI information for a |File|."
However, I used a return comment more akin to what you suggested.

>
>
>      /**
>       * 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.
got it.
>
>      /**
>       * 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.
I was looking into what this does and meandered on to the File doc and 
kind of borrowed the javadoc idea from there, since this
does the same.    I put it back to the original.

-steve

>
> 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
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/swing-dev/attachments/20140424/1a16a7da/attachment.html>