Improve error messages for annotation methods on synthetic TypeVariables

[lmcrean]

Problem

Synthetic TypeVariables created by TypeResolver throw unhelpful UnsupportedOperationException("methodName") when annotation methods are called.

Addresses TODO b/147144588 in TypeResolver.java:371-374.

Solution

Add helpful error messages explaining why annotations aren't supported and what to do instead.

Changes:

1. Convert TODO to NOTE documenting the intentional limitation
2. Add descriptive error for annotation methods with bug reference

Impact

• Better developer experience through clear error messages
• No functional changes
• 2 files modified

Testing

# Verify existing tests still pass
./mvnw test -f guava-tests/pom.xml -Dtest="TypeResolverTest,TypesTest"

All existing tests pass without modification, confirming backward compatibility.

Example Error Message

Before:

UnsupportedOperationException: isAnnotationPresent

After:

UnsupportedOperationException: Annotation methods are not supported on synthetic
TypeVariables created during type resolution. The semantics of annotations on
resolved types with modified bounds are undefined. See b/147144588.

Breaking Changes

None. This change only improves error messages. All existing behavior is preserved:

• Same exceptions thrown
• Same methods unsupported
• No new TypeVariable creation
• No API changes

[lmcrean]

@cpovirk I took a shot at implementing the TypeVariable annotation support you identified in TODO: b/147144588. Does this approach align with what you had in mind? Happy to adjust if needed.

[cpovirk]

Unfortunately, a big part of the problem is that I don't even know what behavior would make sense here :( I am a little fuzzy at the moment even on the exact circumstances that we end up using our own TypeVariable implementation in the first place (capture conversion? substitution (e.g., resolveType, where)?). Then there's the question of what should happen to annotations during such operations, especially given that the handling in javac itself has changed over time. It's also possible that "proper" handling of annotations would mean returning our own TypeVariable implementation more often instead of the original JDK object (e.g., when substituting in @Nullable E for E?), and that could break existing users.

We say every so often that we should get together a list of issues for which it's reasonably like that we actually would try to take a patch. The most recent such list that I have covers:

• Testlib: Add test that putIfAbsent replaces a null value  #6217
• Look for other Maven artifacts that contain Guava classes, and list them in our metadata #6666
• unreleased resource : streams #5756
• Make Iterators.mergeSorted() stable #5773

[lmcrean]

@cpovirk thanks for the guidance, i have minimised the impact of this pr in light of what you said to focus on the error message.

In the TypeResolver note I have used language to be more like "Until there's a clear specification for what annotations should mean on resolved TypeVariables..."

[cpovirk]

Thanks. One comment below.

[cpovirk]

I see some others at https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/reflect/AnnotatedElement.html. Some are default methods, whose behavior I'd have to check under Proxy, but I'd imagine we'd want to cover at least getAnnotations() and possibly the default ones, too.

[lmcrean]

Thanks for catching this. While the existing startsWith checks technically already cover getAnnotations() and getDeclaredAnnotations(), I've added them explicitly for clarity. This mainly makes it crystal clear that we're handling these specific methods, and serves as defensive programming if one of the other startsWith approaches ever changes.

[cpovirk]

Ah, thanks, clearly I missed the detail of startsWith entirely. Maybe we should be doing methodName.contains("Annotat") or something :) I'll see if an internal reviewer has an opinion when I import this now.