<Swing Dev> Review Request for 8040893: fix doclint block tag issues in swing border classes
Steve Sides
steve.sides at oracle.com
Mon Apr 21 19:54:49 UTC 2014
On 4/21/2014 2:45 AM, Alexander Scherbatiy wrote:
>
> 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.
I thought about that, but the method signature is
public *int*getBevelType()
and I wasn't sure if saying it returns "RAISED or LOWERED" clearly
matched the signature. I will make it so.
>
> ------------------------
> /**
> * 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}
okay, http://cr.openjdk.java.net/~ssides/8040893/8040893.2/ has
changes for above
thanks for the quick feedback,
-steve
>
> 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
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/swing-dev/attachments/20140421/3c985cb5/attachment.html>
More information about the swing-dev
mailing list