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