<Swing Dev> [11] Review Request: 6684386 ElementIterator javadoc bug

[Semyon Sadetsky]

On 12/18/2017 08:20 PM, Sergey Bylokhov wrote:

> Hi, Semyon.
> On 18/12/2017 17:52, Semyon Sadetsky wrote:
>> Please, surround with <blockquote> the code sample.
>
> Why <blockquote> should be used since an example is not a "quote" but 
> contains code? I guess <pre>{@code} should be enough.
This is just a good practice to separate a code snippet from the rest of 
text in javadoc.
>
>>
>> All references like
>>
>> * ...if {@code next()} is called before...
>>
>> better to replace with
>>
>> * ...if {@link #next()} is called before...
>
> It always confused me when to use @link instead of @code. Currently I 
> use @code everywhere except the place where I write something like
> "Please see {@link java.beans.XMLEncoder}."
> or something like
> "Refer to {@link #setValueContainsLiteralCharacters} for details"
>
> In other words @link is necessary when the description of referred 
> object has some additional information. Otherwise we had to use @link 
> instead of @code everywhere.
I suggest to take care about readers. In this specific case it is hard 
to realize a phrase like

..if next() is called before first() or current() the root will be 
returned..

in the class specification without knowledge what are those next(), 
first() and current().
>
>
>>
>> --Semyon
>>
>> On 12/18/2017 03:28 PM, Sergey Bylokhov wrote:
>>> Hello.
>>> Please review the fix for jdk11.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-6684386
>>> Webrev can be found at: 
>>> http://cr.openjdk.java.net/~serb/6684386/webrev.00
>>> Specdiff: 
>>> http://cr.openjdk.java.net/~serb/6684386/specdiff.00/javax/swing/text/ElementIterator.html 
>>>
>>>
>>> Description of the javadoc changes:
>>>  - <pre> tag is added for the code in the example
>>>  - the typo in the code was fixed(it.next(")
>>>  - <ul> tag is added for the list
>>>  - The rest of the file was updated to use a styles used in the 
>>> previous javadoc related fixes.
>>>
>>
>
>