8239092: Provide explicit specification for getKind methods of javax.lang.model

Reviewed-by: jjg, prappo

src/java.compiler/share/classes/javax/lang/model/element/Element.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -78,6 +78,43 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
     /**
      * 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();

src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -161,6 +161,24 @@ public interface ModuleElement extends Element, QualifiedNameable {
     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
          */

src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -62,6 +62,46 @@ public interface TypeMirror extends javax.lang.model.AnnotatedConstruct {
     /**
      * 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} is one
+     * of {@link TypeKind#VOID VOID}, {@link TypeKind#PACKAGE
+     * PACKAGE}, {@link TypeKind#MODULE MODULE}, or {@link
+     * TypeKind#NONE NONE}.
+     *
+     * <li> The kind of a {@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();