When we have

@NonNull 
@UiContext 
@override 
@MainThread
public Context foo()

@Nullable and @UiContext conceptually refer to the Context, the return type, while @override and @MainThread refer to the function.

As far as I know, this is because pre-Java-8, AnnotationTarget.TYPE did not exist. I believe the most correct way to have that code in the post-Java-8-world is

@override 
@MainThread
public @NonNull @UiContext Context foo()

Proposal: migrate all (androidx) annotations that conceptually refer to types away from AnnotationTarget.Method(/Getter?) to AnnotationTarget.TYPE.
Because:

Compose is trying to get the @TypeBound annotation added to Kotlin, which would allow fun foo(c: @UiContext Context) to throw a compile-time error when passed a non-@UiContext context, if annotation class UiContext was @TypeBound. This could be useful for @*Context and @*Res, among others. Not everything is Kotlin yet, but we should be forward-looking.
Documentation is ambiguous. How do you know whether to put the four annotations in the top example on the function or on the return type? Right now, there's no way to tell, so Jetbrains duplicates them. Metalava should probably care about this too, at least in some cases. Currently, we use an explicit list in our dokka extension, which is fragile and not future-proof.
This is more correct, and being more correct is being more future-proof and has other benefits, e.g. reputational.

The annotations I believe this applies to:
KNOWN_TYPEBOUND_ANNOTATION_NAMES = "Dimension", "Px", "Size"
KNOWN_TYPEBOUND_ANNOTATION_SUFFIXES = listOf("Res", "Range", "Long", "Int", "Float", "Context")
Including nullability annotations, this comes out to 35 androidx annotations at the current time.

Plan:

Ensure all androidx annotations that should be propagated now permit AnnotationTarget.TYPE.
Move to migrate all androidx usages of those androidx annotations onto the return type.
Ask Jetbrains to get a way to allow @Deprecateing certain AnnotationTargets and deprecate AnnotationTarget.METHOD for the applicable androidx annotations.
Add guidance (docs, lint, dokka?) to recommend that others (the rest of Google, external developers, and all annotation providers) migrate all applicable annotations onto return types, mentioning the java8 history. Ideally coordinate with Jetbrains to get their support.
Eventually, after at least one major version bump of androidx.annotation, remove the deprecated AnnotationTarget.METHOD.
If @TypeBound is accepted, consider how it could be made use of.

Caveat: this is assuming the minimum java version we support is Java8. I believe this is the case, or will be by the time we reach step 5 (and that lower versions are deprecated by step 3). Do we have an official policy on this topic?

Issue 196578473

Mentioned issues (4)

Links (5)

Issue metadata