Summary

Add explicit specifications for the various getKind methods in the javax.lang.model API.

Problem

The getKind methods do not explicit state the constraints on the type-to-kind mapping. While many of the mappings are obvious , a "FooElement" has a kind of "FOO", some types have multiple possible kinds. For elements and types, the possible one-to-many mappings are captured in the FooKind visitor classes.

Solution

In the root interfaces, add lists describing the possible type-to-kind mapping. This is done in preference to adding getKind overrides in each type.

Specification

--- old/src/java.compiler/share/classes/javax/lang/model/element/Element.java   2020-02-14 09:29:39.476001000 -0800
+++ new/src/java.compiler/share/classes/javax/lang/model/element/Element.java   2020-02-14 09:29:38.936001000 -0800
@@ -78,6 +78,43 @@
     /**
      * Returns the {@code kind} of this element.
      *
+     * <ul>
+     *
+     * <li> The kind of a {@linkplain PackageElement package} is
+     * {@link ElementKind#PACKAGE PACKAGE}.
+     *
+     * <li> The kind of a {@linkplain ModuleElement module} is {@link
+     * ElementKind#MODULE MODULE}.
+     *
+     * <li> The kind of a {@linkplain TypeElement type element} is one
+     * of {@link ElementKind#ANNOTATION_TYPE ANNOTATION_TYPE}, {@link
+     * ElementKind#CLASS CLASS}, {@link ElementKind#ENUM ENUM}, {@link
+     * ElementKind#INTERFACE INTERFACE}, or {@link ElementKind#RECORD
+     * RECORD}.
+     *
+     * <li> The kind of a {@linkplain VariableElement variable} is one
+     * of {@link ElementKind#ENUM_CONSTANT ENUM_CONSTANT}, {@link
+     * ElementKind#EXCEPTION_PARAMETER EXCEPTION_PARAMETER}, {@link
+     * ElementKind#FIELD FIELD}, {@link ElementKind#LOCAL_VARIABLE
+     * LOCAL_VARIABLE}, {@link ElementKind#PARAMETER PARAMETER},
+     * {@link ElementKind#RESOURCE_VARIABLE RESOURCE_VARIABLE}, or
+     * {@link ElementKind#BINDING_VARIABLE BINDING_VARIABLE}.
+     *
+     * <li> The kind of an {@linkplain ExecutableElement executable}
+     * is one of {@link ElementKind#CONSTRUCTOR CONSTRUCTOR}, {@link
+     * ElementKind#INSTANCE_INIT INSTANCE_INIT}, {@link
+     * ElementKind#METHOD METHOD}, or {@link ElementKind#STATIC_INIT
+     * STATIC_INIT}.
+     *
+     * <li> The kind of a {@linkplain TypeParameterElement type parameter} is
+     * {@link ElementKind#TYPE_PARAMETER TYPE_PARAMETER}.
+     *
+     * <li> The kind of a {@linkplain RecordComponentElement record
+     * component} is {@link ElementKind#RECORD_COMPONENT
+     * RECORD_COMPONENT}.
+     *
+     * </ul>
+     *
      * @return the kind of this element
      */
     ElementKind getKind();
--- old/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 2020-02-14 09:29:40.424001000 -0800
+++ new/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 2020-02-14 09:29:39.992001000 -0800
@@ -161,6 +161,24 @@
     interface Directive {
         /**
          * Returns the {@code kind} of this directive.
+         * <ul>
+         *
+         * <li>The kind of a {@linkplain RequiresDirective requires
+         * directive} is {@link DirectiveKind#REQUIRES REQUIRES}.
+         *
+         * <li>The kind of an {@linkplain ExportsDirective exports
+         * directive} is {@link DirectiveKind#EXPORTS EXPORTS}.
+         *
+         * <li>The kind of an {@linkplain OpensDirective opens
+         * directive} is {@link DirectiveKind#OPENS OPENS}.
+         *
+         * <li>The kind of a {@linkplain UsesDirective uses
+         * directive} is {@link DirectiveKind#USES USES}.
+         *
+         * <li>The kind of a {@linkplain ProvidesDirective provides
+         * directive} is {@link DirectiveKind#PROVIDES PROVIDES}.
+         *
+         * </ul>
          *
          * @return the kind of this directive
          */
--- old/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java   2020-02-14 09:29:41.244001000 -0800
+++ new/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java   2020-02-14 09:29:40.844001000 -0800
@@ -62,6 +62,47 @@
     /**
      * Returns the {@code kind} of this type.
      *
+     * <ul>
+     *
+     * <li> The kind of a {@linkplain PrimitiveType primitive type} is
+     * one of the kinds for which {@link TypeKind#isPrimitive} returns
+     * {@code true}.
+     *
+     * <li> The kind of a {@linkplain NullType null type} is {@link
+     * TypeKind#NULL NULL}.
+     *
+     * <li> The kind of an {@linkplain ArrayType array type} is {@link
+     * TypeKind#ARRAY ARRAY}.
+     *
+     * <li> The kind of a {@linkplain DeclaredType declared type} is
+     * {@link TypeKind#DECLARED DECLARED}.
+     *
+     * <li> The kind of an {@linkplain ErrorType error type} is {@link
+     * TypeKind#ERROR ERROR}.
+     *
+     * <li> The kind of a {@linkplain TypeVariable type variable} is
+     * {@link TypeKind#TYPEVAR TYPEVAR}.
+     *
+     * <li> The kind of a {@linkplain WildcardType wildcard type} is
+     * {@link TypeKind#WILDCARD WILDCARD}.
+     *
+     *
+     * <li> The kind of an {@linkplain ExecutableType executable type}
+     * is {@link TypeKind#EXECUTABLE EXECUTABLE}.
+     *
+     * <li> The kind of a {@linkplain NoType pseudo-type type} is one
+     * of {@link TypeKind#VOID VOID}, {@link TypeKind#PACKAGE
+     * PACKAGE}, {@link TypeKind#MODULE MODULE}, or {@link
+     * TypeKind#NONE NONE}.
+     *
+     * <li> The kind of an {@linkplain UnionType union type} is {@link
+     * TypeKind#UNION UNION}.
+     *
+     * <li> The kind of an {@linkplain IntersectionType intersection
+     * type} is {@link TypeKind#INTERSECTION INTERSECTION}.
+     *
+     * </ul>
+     *
      * @return the kind of this type
      */
     TypeKind getKind();