RFR: 8266666: Implementation for snippets [v2]

[Pavel Rappo]

On Tue, 27 Jul 2021 11:06:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update @since tags

> _Mailing list message from [Jonathan Gibbons](mailto:jonathan.gibbons at oracle.com) on [javadoc-dev](mailto:javadoc-dev at mail.openjdk.java.net):_
> 
> The comments don't need to be of core-libs quality, but at least some of
> the problems we have had in the code of late has been discerning the
> original intent, so at least some amount of comment/documentation is
> useful, even if we don't run it through javadoc or even doclint.
> 
> Think of the comments as "pay it forward" to our future selves.
> 
> -- Jon
> 
> On 7/26/21 5:09 AM, Pavel Rappo wrote:
> 
> > I'm ok with adding the boilerplate "This is NOT part of any supported API" note, as well as adding method comments where practical. However, I note that this PR comprises mostly an internal implementation and not a public API. Internal implementation comments are more like documentation rather than specification. Such documentation is virtually never built and is read in an IDE while eyeballing the respective code and tests. I think it's overkill and waste of resources to use doc comments in such a case.

Project conventions are more important than my preferences. Although I don't see much value in such comments, I added some in commit 4300903.

-------------

PR: https://git.openjdk.java.net/jdk/pull/4795