<Swing Dev> Review Request for 8044261: Fix doclint warnings (missing javadoc @param and @return tags) in javax.swing.text - Part 1 of 2

[Rocky Sloan]

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