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
