[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList

[Jaikiran Pai]

Hello Bernd,

Thank you for the review and sorry about the delayed response. Comments
inline.

On 29/08/18 4:26 PM, Bernd Eckenfels wrote:
> Hello,
>
> Not an Reviewer But just wanted to give a short Feedback: I like the
> new Version it is really helpful. 
>
> However I wonder if the usage example should be outside of the apinote.

+     * @apiNote
+     * This method also provides a convenient way to create a fixed-size
      * list initialized to contain several elements:
      * <pre>
      *     List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
      * </pre>
      *

My limited understanding of the @apiNote is that it is supposed to be
used for additional details of the API and/or its usage examples and the
javadoc itself (outside of the @apiNote) should be a specification of
the API. In this case, I moved that section to @apiNote since that part
appears to mention how/when to use that API in. Having said that, I can
move it out of @apiNote and let it stay the way it previously was, if
you and others feel that's the way to go.

>
> Given the existence of List.of() I wonder if you either mention it as
> a alternative to the example (with slightly different semantic) or
> just remove the sample completely?

I'm not too sure mentioning List.of() construct here will be useful, but
I do see why you mention that. I think the existing example does seem
like a useful usage example, irrespective of whether or not we decide to
have it in or outside of an @apiNote.

-Jaikiran