[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList
ecki at zusammenkunft.net
Thu Sep 6 07:54:47 UTC 2018
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?
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
Thank you for the review and sorry about the delayed response. Comments inline.
On 29/08/18 4:26 PM, Bernd Eckenfels wrote:
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:
* List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
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.
More information about the core-libs-dev