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

[Bernd Eckenfels]

Yes you are right @apinote is aproperiate section (was confusing it with implnote).

Still think a ‚literal specified list‘ is no longer a good (as in canonical) usecase for that method.

I used it in the past often to get a List for using toString() on it, but I guess even for that case List.of can be used instead now.

So @see List#of and let the reader figure out when to use them?

Gruss
Bernd
--
http://bernd.eckenfels.net

________________________________
Von: Jaikiran Pai <jai.forums2013 at gmail.com>
Gesendet: Donnerstag, September 6, 2018 9:13 AM
An: Bernd Eckenfels; core-libs-dev at openjdk.java.net
Betreff: Re: [PATCH] JDK-7033681 - Improve the documentation of Arrays.asList



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