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

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