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
