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

[Jonathan Gibbons]

On 8/4/20 12:18 PM, Florian Weimer wrote:
> * 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.
It would be surprising (bug?) to see a warning being generated for a 
class that
is not being documented.  I assume you have not given command-line options
to include that class in the documentation.  I'm also guessing that this is
while using javadoc, where the recent change occurred; not javac.

I can also try and recreate the issue, based on what you have said so far.

-- Jon