Summary
-------

Add a method to strip annotations from type mirrors to `javax.lang.model.util.Types` and clarify how existing methods in `Types` treat annotations.

Problem
-------

The current API does not specify how type annotations are propagated, or not, on `Types`' methods and there is no facility to generate a type without its annotations.

Solution
--------
Add the a new method and clarify existing methods.

Specification
-------------

    diff --git a/src/java.compiler/share/classes/javax/lang/model/util/Types.java b/src/java.compiler/share/classes/javax/lang/model/util/Types.java
    index 8c3cc7ba5d98..93b43c777be5 100644
    --- a/src/java.compiler/share/classes/javax/lang/model/util/Types.java
    +++ b/src/java.compiler/share/classes/javax/lang/model/util/Types.java
    @@ -1,5 +1,5 @@
     /*
    - * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved.
    + * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
      * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
      *
      * This code is free software; you can redistribute it and/or modify it
    @@ -35,6 +35,10 @@
     /**
      * Utility methods for operating on types.
      *
    + * Where a method returns a type mirror or a collection of type
    + * mirrors, any type mirrors represent types with no type annotations,
    + * unless otherwise indicated.
    + *
      * <p><b>Compatibility Note:</b> Methods may be added to this interface
      * in future releases of the platform.
      *
    @@ -153,6 +157,8 @@ public interface Types {
          * the direct supertypes of a type mirror representing {@code
          * java.lang.Object}.
          *
    +     * Annotations on the direct super types are preserved.
    +     *
          * @param t  the type being examined
          * @return the direct supertypes, or an empty list if none
          * @throws IllegalArgumentException if given a type for an executable, package, or module
    @@ -235,6 +241,8 @@ public interface Types {
         /**
          * {@return an array type with the specified component type}
          *
    +     * Annotations on the component type are preserved.
    +     *
          * @param componentType  the component type
          * @throws IllegalArgumentException if the component type is not valid for
          *          an array
    @@ -245,6 +253,8 @@ public interface Types {
          * {@return a new wildcard type}  Either of the wildcard's
          * bounds may be specified, or neither, but not both.
          *
    +     * Annotations on the bounds are preserved.
    +     *
          * @param extendsBound  the extends (upper) bound, or {@code null} if none
          * @param superBound    the super (lower) bound, or {@code null} if none
          * @throws IllegalArgumentException if bounds are not valid
    @@ -260,6 +270,8 @@ WildcardType getWildcardType(TypeMirror extendsBound,
          * for example, this method may be used to get the
          * parameterized type {@code Set<String>}.
          *
    +     * Annotations on the type arguments are preserved.
    +     *
          * <p> The number of type arguments must either equal the
          * number of the type element's formal type parameters, or must be
          * zero.  If zero, and if the type element is generic,
    @@ -291,6 +303,8 @@ WildcardType getWildcardType(TypeMirror extendsBound,
          * to get the type {@code Outer<String>}, and then invoking
          * this method.
          *
    +     * Annotations on the type arguments are preserved.
    +     *
          * <p> If the containing type is a parameterized type,
          * the number of type arguments must equal the
          * number of {@code typeElem}'s formal type parameters.
    @@ -324,4 +338,29 @@ DeclaredType getDeclaredType(DeclaredType containing,
          *          for the given type
          */
         TypeMirror asMemberOf(DeclaredType containing, Element element);
    +
    +    /**
    +     * {@return a type mirror equivalent to the argument, but with no annotations}
    +     * If the type mirror is a composite type, such as an array type
    +     * or a wildcard type, any constitute types, such as the
    +     * component type of an array and the type of the bounds of a
    +     * wildcard type, also have no annotations, recursively.
    +     *
    +     * <p>For most kinds of type mirrors, the result of
    +     * {@snippet lang="java" :
    +     *   types.isSameType(typeMirror, types.stripAnnotations(typeMirror))
    +     * }
    +     * is {@code true}. The predicate is {@code false} on wildcard
    +     * types for {@linkplain #isSameType(TypeMirror, TypeMirror)
    +     * reasons discussed elsewhere}.
    +     *
    +     * @param t the type mirror
    +     * @param <T> the specific type of type mirror
    +     * @implSpec
    +     * The default implementation throws {@code UnsupportedOperationException}.
    +     * @since 23
    +     */
    +    default <T extends TypeMirror> T stripAnnotations(T t) {
    +        throw new UnsupportedOperationException();
    +    }
     }