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.
3. The "owner type" concept has been unclear.
4. Confusing specifications, such as that of `ParameterizedType::getRawType`, "class or interface that declares this type".
5. 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/8343251-apidiff/java.base/java/lang/reflect/package-summary.html during active review period.