Standard set of declaration-annotation equivalents to @Nullable and @NonNull

[cpovirk]

I'm opening this issue because I thought we already had an issue filed about it, but I can't find it.

Maybe I can't find it because I'm confusing "declaration vs. type-use" with "runtime retention vs. class retention" (#28, #96, #234), which was another case in which we speculated that we might want a second set of annotations—or, alternatively, to let users define their own by using @Implies. Of course, as that other case suggests, there is a slippery (but possibly short?) slope that could lead to our introducing @NullableDecl, @NullableDeclNoRuntime, @NonNullDecl, and @NonNullDeclNoRuntime—and setting a precedent that possible future features like @PolyNull might follow, too.

The question of declaration annotations was briefly on my mind recently when I elected to use declaration annotations over JSpecify annotations for one particular system. That system is a code generator that uses string templating, so it was convenient to be able to write something like "@javax.annotation.CheckForNull {returnType}." (The obvious choice, "@org.jspecify.annotations.Nullable {returnType}" would have been wrong because it would have generated "@org.jspecify.annotations.Nullable java.lang.String" rather than the necessary "java.lang.@org.jspecify.annotations.Nullable String." Of course, in an ideal world, the code generator would provide a good way to annotate types, as I assume that popular code-generation libraries do and as other libraries have done by hand (e.g., AutoValue, IIRC).

The other use case I've heard of for declaration annotations is code that targets Java 7 or lower. (My experience suggests that it's actually possible to use type-use annotations with -source 7 and have them treated much like declaration annotations. But there may well be edge cases in which that doesn't work completely correctly.) Thankfully, that's become an even rarer use case than it was when we started out.

The other bit of good news is that there are so many existing declaration annotations to choose from. So, as long as the need for declaration annotations is fairly rare, I don't think we need to rush in to fill it with yet more annotations.

I think this has been the consensus position in past discussions: We could be talked into offering declaration annotations someday if there were a great enough need, but such annotations aren't part of a 1.0 offering, and we'd be happy if we could get away without them even afterward (thanks to lack of need or to @Implies). So I'm going to close this issue as soon as I create it. Still, we can use it to collect other relevant information as it arises.

[cpovirk]

(I might also have been confusing this with discussion of supporting Java 7 users by generating Java 7 bytecode.)

[netdpb]

Current decision: This feature is not required for JSpecify 1.0.

Proposal for 1.0: Finalize the current decision. If you agree, please add a thumbs-up emoji (👍) to this comment. If you disagree, please add a thumbs-down emoji (👎) to this comment and briefly explain your disagreement. Please only add a thumbs-down if you feel you can make a strong case why this decision will be materially worse for users or tool providers than an alternative.