Review Request: 7193710 ByteArrayOutputStream Javadoc contains unclosed <code> element

[Dan Xu]

I will update the change with your suggestion. Thanks!

-Dan



On 08/28/2012 04:52 PM, Ulf Zibis wrote:
> Thanks for your feedback Dan.
>
> But I still think, the link to the javadoc of a class should not be 
> labelled by a variable name.
> So maybe use:
>  212      * Converts the buffer's contents into a string by decoding 
> the bytes using
>  213      * the {@link java.nio.charset.Charset}, specified by it's 
> name. The length of
> or:
>  212      * Converts the buffer's contents into a string by decoding 
> the bytes using
>  213      * the {@link java.nio.charset.Charset}, specified by it's 
> {@code charsetName}.
> And:
>  222      * @param  charsetName  the name of a supported
>  223      *         {@link java.nio.charset.Charset}
>
> -Ulf
>
> Am 29.08.2012 01:39, schrieb Dan Xu:
>> Thanks for your comments, Ulf.
>>
>> I looked at the definitions of @link and @linkplain again. And I find 
>> that this nested situation can be easily avoided by replacing 
>> @linkplain with @link as the following,
>>
>>     {@link java.nio.charset.Charset charset}
>>
>> I will update my changes.
>>
>> -Dan
>>
>>
>>
>> On 08/28/2012 02:20 PM, Ulf Zibis wrote:
>>> Am 28.08.2012 11:45, schrieb Alan Bateman:
>>>> On 27/08/2012 21:48, Dan Xu wrote:
>>>>> This change is to fix the java doc font issue for 
>>>>> ByteArrayOutputStream class. In current javadoc, contents change 
>>>>> to the wrong font starting from toString(String charsetName) in 
>>>>> ByteArrayOutputStream.html, which can be viewed at 
>>>>> http://docs.oracle.com/javase/7/docs/api/java/io/ByteArrayOutputStream.html.
>>> I think the link to the javadoc of a class should not be labelled by 
>>> a variable name:
>>>  212      * Converts the buffer's contents into a string by decoding 
>>> the bytes using
>>>  213      * the specified {@link java.nio.charset.Charset 
>>> charsetName}. The length of
>>> Maybe better:
>>>  212      * Converts the buffer's contents into a string by decoding 
>>> the bytes using
>>>  213      * the {@link java.nio.charset.Charset}, specified by it's 
>>> name. The length of
>>> or:
>>>  212      * Converts the buffer's contents into a string by decoding 
>>> the bytes using
>>>  213      * the {@link java.nio.charset.Charset}, specified by it's 
>>> [@code charsetName}. The length of
>>> Same for:
>>>  222      * @param  charsetName  the name of a supported
>>>  223      *              {@link(plain) java.nio.charset.Charset}
>>>
>>> Additionally you could align the param items:
>>>  224      * @return  String decoded from the buffer's contents.
>>>  225      * @throws UnsupportedEncodingException
>>>  226      *         If the named charset is not supported
>>>  227      * @since  JDK1.1
>>>
>>>  227      * @since  JDK1.1
>>> Shouldn't it be? :
>>>  227      * @since  1.1
>>>
>>>>> The webrev is at http://cr.openjdk.java.net/~dxu/7193710/webrev/.
>>>> This looks fine me as it doesn't seem you can use @code here (Joe 
>>>> or Jon might be able to say what the rules are for nesting these 
>>>> javadoc tags).
>>> Interesting question, maybe a bug in javadoc?
>>> Maybe {@link ...} instead {@linkplain ...} would work.
>>>
>>> +1 for taking the opportunity to upgrade the file to using {@code}, 
>>> {@link}, <tt>...</tt> to {@code ...} etc., even if in this special 
>>> nested case a trick is needed.
>>>
>>> -Ulf
>>>
>>
>>
>