RFR: 8266666: Implementation for snippets

[Pavel Rappo]

On Thu, 15 Jul 2021 14:13:16 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.

>
> * All new top-level classes should have a reasonable documention comment, including where appropriate the standard boilerplate (i.e. not on public API classes and interfaces)
>   *  <p><b>This is NOT part of any supported API.
>   *  If you write code that depends on this, you do so at your own risk.
>   *  This code and its internal interfaces are subject to change or
>   *  deletion without notice.
> * All new non-private methods should have a reasonable documentation comment
>

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.

>
> * There's more than a typical number of chatty comments and/or fixme comments and/or code that needs to be uncommented.   I'll do a separate review pass to note some of those examples.
>

I'm currently working on removing as many FIXMEs and TODOs as possible. I think of a FIXME comment as a "review breakpoint" that highlights an issue that has to be resolved before the code is accepted. 

I would be interested to learn which comments you consider "chatty". I look forward to fixing them with your help. One note, though. For an internal implementation, I try hard to make only the "why" comments, not the "what" comments. "What" comments have their place, but they should be sparing and reserved for non-trivial domains. For trivial domains, the "what" should be obvious. If it is not, I failed at coding, not at commenting.

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

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