<Swing Dev> Review Request for 8040893: fix doclint block tag issues in swing border classes

Alexander Scherbatiy alexandr.scherbatiy at oracle.com
Mon Apr 21 09:45:09 UTC 2014


Hello Steve,

------------------------
      /**
       * Returns the type of the bevel border.
+     *
+     * @return 0 if the bevel type is {@code RAISED}, 1 if {@code LOWERED}
       */
------------------------

I think such description reveals unnecessary level of code abstraction.
Developers always need to use BevelBorder.RAISED and BevelBorder.LOWERED 
constant and never their numerical representation.
It would better to say that the method return the bevel type: RAISED or  
LOWERED.

------------------------
      /**
       * Returns whether or not the border is opaque.
+     *
+     * @return true
       */
      public boolean isBorderOpaque() { return true; }
------------------------
It would better to also add the similar comment from the parent 
AbstractBorder class like: "This implementation returns true".
It seems that the "code" tag can be used with boolean values: {@code true}

Thanks,
Alexandr.

On 4/18/2014 2:48 AM, Steve Sides wrote:
> Hello,
>
> Could you please review the fix for the following bug:
> https://bugs.openjdk.java.net/browse/JDK-8040893
>
> Webrev corresponding:
> http://cr.openjdk.java.net/~ssides/8040893/
>
> webrevComment.txt:
> This addresses missing @parm and @return block tags in javadoc for
> javax/swing/border classes as noted by doclint.
>
> It does not address methods which are missing javadoc comment altogether,
> of which there are many.
>
> It also a adds @return to isBorderOpaque() methods which were incorrectly
> inheriting the default, @return false, from AbstractBorder.
>
>
> thanks,
>
> -steve
>




More information about the swing-dev mailing list