<Swing Dev> Review Request for 8044261: Fix doclint warnings (missing javadoc @param and @return tags) in javax.swing.text - Part 1 of 2
Petr Pchelko
petr.pchelko at oracle.com
Thu Jul 17 08:26:23 UTC 2014
Hello, Rocky.
> I have corrected 2,3,4,6.
Thank you. Where can I find an updated webrev?
Looks like we are trying to conform to the following pattern:
> * @param chars character array containing content to write
> * @param startIndex offset in the array to start writing from;
> * 0 starts at the beginning
> * @param length number of characters to write
> If the formatting you prefer does not match existing tags for the method, should I modify the existing tags (in the method or entire file) to conform to the new formatting?
I think the best thing to do is to modify the doc of the method you touch. The entire file is way too much and having a single method with different formatting looks bad...
With best regards. Petr.
On 16 июля 2014 г., at 11:41, Rocky Sloan <rocky.sloan at oracle.com> wrote:
> Hi Petr,
>
> Thanks for the comments.
>
> I have corrected 2,3,4,6.
>
> As far as the indentation and line continuation format, I am still a bit unclear and I want to make sure I get it right for you.
>
> Generally, I follow the usage currently in place within that file (one or two spaces after the param/return, how multiple line indentations are handled, etc).
>
> For tags with multiple lines, I will follow the local usage within the file by indenting one or two spaces (or line them up in a block, especially when multiple multi-line tags become unclear).
>
> For some quick perspective, here is a blurb from the reference document Steve mentioned:
>
> ----------------------
> "Additional spaces can be inserted between the name and description so that the descriptions line up in a block."
>
> Example:
>
> * @param ch the character to be tested
> * @param observer the image observer to be notified
> ----------------------
>
> I particularly tend to do this when multiple multi-line tags start looking messy.
>
> In AbstractWriter, I used this style (block-formatted descriptions):
>
> * @param chars character array containing content to write
> * @param startIndex offset in the array to start writing from;
> * 0 starts at the beginning
> * @param length number of characters to write
>
> You requested this:
>
> * @param chars character array containing content to write
> * @param startIndex offset in the array to start writing from;
> * 0 starts at the beginning
> * @param length number of characters to write
>
> that is, single space after the param name, and arbitrary indent on the tag with multiple lines.
> The question for this style is, what is the rule for how far to indent the second line?
>
> I have seen the following variation in many files (indent one or two spaces upon line continuation):
>
> * @param chars character array containing content to write
> * @param startIndex offset in the array to start writing from;
> * 0 starts at the beginning
> * @param length number of characters to write
>
> or this (second line text lines up with start of description):
>
> * @param chars character array containing content to write
> * @param startIndex offset in the array to start writing from;
> * 0 starts at the beginning
> * @param length number of characters to write
>
> Let me know what will work for you.
>
> Many files use a single space after the @param name or @return, others use two spaces (like in the reference doc, but it also uses <code></code>...)
> In some files, the first word of the @param/@return description is capitalized, and the sentence ends in a period.
> Of course, block formatting (as above) is used here and there.
>
> I also avoid modifying the existing tags and instead try to conform to them (unless something obvious needs fixing).
> If the formatting you prefer does not match existing tags for the method, should I modify the existing tags (in the method or entire file) to conform to the new formatting?
>
> Thanks again!
>
> Best Regards,
>
> Rocky
>
> On 7/10/2014 3:39 AM, Petr Pchelko wrote:
>> Hello, Rocky.
>>
>> A couple of comments.
>>
>> 1. Please control the correct indentation of the second line of the @param/@return tag descriptions. You have many places where it's incorrect.
>> 2. Please use @code instead of <code></code>
>> 3. AbstractWriter - no need to mention variable names in the javadoc. Please remove it.
>> 4. AbstractWriter:374 - better to say {@code true} if the lines will be wrapped, {@code false} otherwise. Also please remove the last line of the doc.
>> 5. The indentation of @param comments is incorrect. You have:
>>> * @param chars character array containing content to write
>>> * @param startIndex offset in the array to start writing from;
>>> * 0 starts at the beginning
>>> * @param length number of characters to write
>> And you should have:
>>> * @param chars character array containing content to write
>>> * @param startIndex offset in the array to start writing from;
>>> * 0 starts at the beginning
>>> * @param length number of characters to write
>> 6. AsyncBoxView:451 - it's not a boolean!
>>
>> With best regards. Petr.
>>
>> On 10 июля 2014 г., at 13:36, Rocky Sloan<rocky.sloan at oracle.com> wrote:
>>
>>> Hello,
>>>
>>> Could you please review Part 1 of the fix for the following bug:
>>> https://bugs.openjdk.java.net/browse/JDK-8044261
>>>
>>> This is part 1 of 2.
>>>
>>> Webrev corresponding:
>>> http://cr.openjdk.java.net/~yan/8044261/webrev.01/
>>>
>>> Change:
>>> Add missing @return and @param javadoc tags in javax.swing.text classes to fix doclint warnings.
>>>
>>> Thanks,
>>>
>>> - Rocky
>>>
>
More information about the swing-dev
mailing list