<Swing Dev> Review Request for 8040893: fix doclint block tag issues in swing border classes
Alexander Scherbatiy
alexandr.scherbatiy at oracle.com
Tue Apr 22 09:03:34 UTC 2014
On 4/21/2014 11:54 PM, Steve Sides wrote:
>
> 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.
This looks good.
There is the javadoc for the
BorderLayout.addLayoutComponent(Component comp, Object constraints)
method that says:
"For border layouts, the constraint must be one of the following
constants: NORTH, SOUTH, EAST, WEST, or CENTER."
and does not mention that NORTH constant is actually the "North" String.
http://docs.oracle.com/javase/7/docs/api/java/awt/BorderLayout.html
Could you also update the javadoc for the EtchedBorder.getEtchType()
method in the same way?
>
>>
>> ------------------------
>> /**
>> * 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
This version looks good for me.
Thanks,
Alexandr.
>
> 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
>>>
>>
>
More information about the swing-dev
mailing list