"no comment" warnings for non-public entities related to serialization

[Florian Weimer]

* Jonathan Gibbons:

> On 8/4/20 11:20 AM, Florian Weimer wrote:
>> I'm not sure how recent this change is, but I noticed that "no
>> comment" warnings are now printed for entities that are related to
>> serialization: non-public classes which implement Serializable, and
>> private non-transient fields in serializable classes, and named
>> private serialization-related methods.
>>
>> I think it might make sense to add a few words to the warning that
>> it's about serialization compatibility.  It took me a moment to
>> realize why javadoc was warning about these constructs.
>
> Hi Florian,
>
> Thanks for the suggestion.  This is a side-effect of a recent bug fix,
> that missing comments were never being detected by doclint in javadoc.
> This was true for all missing comments, not just for declarations and
> comments related to serialization.

Hah.  I had not realized that.  I guess my public methods have already
been documented, just not the things related to serialization.

> I'd be curious if you have seen the warning generated inappropriately.
> For example, you write: `non-public classes which implement Serializable`
> If the class is not being documented, you shouldn't see any warnings
> about anything related to the doc comments for the class.

In certain contexts, I get a doclint warning for:

package enyo.util;

class E extends Exception {
}

src/enyo.core/enyo/util/E.java:3: warning: no comment
class E extends Exception {
^

I expect no warning is expected here?

There's more to it, for a standalone example, I do not get a warning.
I see it with a modular build, where enyo.util is an exported package.
The source file is called E.java and it's on the module source path,
and contains just those four quoted lines.