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
