A meta-annotation to express which TYPE_USE locations are recognized

[cpovirk]

Following #101's earlier proposal of a meta-annotation:

For nullness, we don't assign meaning to annotations in certain locations, like class @Nullable Foo {} and class Foo extends @Nullable Bar. Perhaps we'd want a declarative way to label our annotations to specify which locations are applicable.

(But will we really even define many other type annotations? Maybe, but quite possibly not.)

Not a high priority in any case.

[cpovirk]

The natural way to do this would be with an enum, I guess based on some combination of 9.6.4.1, 9.7.4, and 4.11: @ApplicableLocations({TYPE_ARGUMENT, ARRAY_ELEMENT, ...}).

However:

• I'm not immediately sure whether we'll be able to provide as much expressiveness as we'd want. Notably, we can't say "only on non-primitive types" unless we go beyond pure "locations." (Maybe the same goes for ruling out annotations on enclosing types?) It would be OK for this meta-annotation to not provide complete information, but if we're going to go to the trouble of defining an enum with 16+ values correctly, we'd want to make sure we're getting something important out of it.
• Enums can be trouble: They make it more dangerous for downstream users to omit JSpecify from their classpath. But maybe that doesn't matter so much here because the meta-annotation wouldn't be appearing in user code, only in our own annotation definitions?

[mernst]

For comparison, see the Checker Framework's @DefaultFor meta-annotation.

[cpovirk]

Thanks. One thing I immediately notice is some evidence that even our concept of "location" might need to be more nuanced than the JLS's "16 type contexts": The Checker Framework lets developers distinguish between LOCAL_VARIABLE and RESOURCE_VARIABLE. In other cases, our concept might be better off being less nuanced than the JLS, just as the Checker Framework doesn't offer an enum value for all 16 JLS contexts.

More generally, it seems unlikely that we'd get this right on our first try. Given that, this feature is another that I'd be inclined to postpone.

(Another concern: We could someday find ourselves with 3 categories: "recognized," "not recognized but potentially meaningful to some tools," and "bogus." This would be similar to the "unrecognized"/"intrinsically non-nullable" distinction drawn in #135. Would tools be most interested in knowing "Is this recognized?" or "Is this bogus?" or both? Until we know, it's hard to decide what to put in the meta-annotation and what to call it.)

[kevinb9n]

The one use case we have for this right now would not really benefit very cleanly from this meta-annotation.. there are some very fine-grained distinctions we're having to make.

Needs more use cases.