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

[Ulf Zibis]

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