Incorrect comment?

[AriaAdibi]

auto/common/src/main/java/com/google/auto/common/BasicAnnotationProcessor.java

Line 522 in 00fe738

* <p>Packages declared (and annotated) in {@code package-info.java} are tracked as deferred

I have analyzed the code and I believe the code does not behave as this comment suggests. I believe the deferral policy of (any kind of) package is the same as that of TypeElements. The only peculiar thing about packages is that to check for well-informedness only their annotations are superficially validated and nothing else. Moreover, there is no mention of package-info.java in the code. Am I wrong?

[eamonnmcmanus]

As you say, validating a package consists only of validating the annotations on it. The point about package-info.java is that that is the mechanism for annotating a package:

// com/example/foo/package-info.java

@SomeAnnotation
@SomeOtherAnnotation
package com.example.foo;

Suppose package com.example.foo was one of the elements returned by RoundEnvironment.getElementsAnnotatedWith, and suppose the class SomeOtherAnnotation doesn't exist (because an annotation processor will create it later). Then we will defer an ElementName representing package com.example.foo to a later processing round.

I don't think the comment is wrong per se, but it could possibly be worded better. Feel free to send a PR with a wording that you would have found easier to follow.