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.
