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

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