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<[email protected]> 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
