Summary

General improvements to specifications of Type and AnnotatedType.

Problem

Type and AnnotatedType suffer from these few issues:

1. Difficult onboarding - the model is not straightforward on first sight, especially their exact correspondence with Java types. It's hard to find the right mapping between Java types, Type interfaces, and AnnotatedType interfaces.
2. The "owner type" concept has been unclear.
3. Confusing specifications, such as that of ParameterizedType::getRawType, "class or interface that declares this type".
4. We don't ask to use equals but use ad-hoc docs for equality constraints, such as in TypeVariable and ParameterizedType.

Solution

1. Add Java Language type to modeling interface in the overview for both Type and AnnotatedType. Type is a type, and AnnotatedType is a (potentially annotated) use.
2. Specify the type for different AnnotatedType subinterfaces.
3. Use and describe "inner member class" (from JLS) to replace the "owner type" term for getOwnerType, and refer to it whenever needed to describe a member type.
4. Improve the specification for ParameterizedType::getActualTypeArguments to note the existence of owner types; also for annotated version. Mention that this is "as used in source code", which is what "actual" means.
5. Update ParameterizedType::getRawType to refer to raw types and erasure.
6. Move the equals specification for ParameterizedType to the actual equals method, and advocate the use of equals for all Type/AnnotatedType.

Specification

See the attached apidiff. The latest version will be also available at https://cr.openjdk.org/~liach/apidiff/types-facelift/java.base/java/lang/reflect/package-summary.html during active review period.