On Tue, 27 Jul 2021 11:06:35 GMT, Pavel Rappo <pra...@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.gibb...@oracle.com) on 
> [javadoc-dev](mailto:javadoc-...@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

Reply via email to