8262807: Note assumptions of core reflection modeling and parameter h…

…andling

Reviewed-by: rriggs

src/java.base/share/classes/java/lang/Class.java

@@ -1266,6 +1266,9 @@ private Class<?> elementType() {
      *
      * @return the {@code int} representing the modifiers for this class
      * @see     java.lang.reflect.Modifier
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      * @since 1.1
      * @jls 8.1.1 Class Modifiers
      * @jls 9.1.1. Interface Modifiers

src/java.base/share/classes/java/lang/reflect/Executable.java

@@ -201,8 +201,8 @@ String sharedToGenericString(int modifierMask, boolean isDefault) {
     public abstract String getName();
 
     /**
-     * Returns the Java language {@linkplain Modifier modifiers} for
-     * the executable represented by this object.
+     * {@return the Java language {@linkplain Modifier modifiers} for
+     * the executable represented by this object}
      */
     public abstract int getModifiers();
 
@@ -257,13 +257,20 @@ public int getParameterCount() {
     }
 
     /**
-     * Returns an array of {@code Type} objects that represent the formal
-     * parameter types, in declaration order, of the executable represented by
-     * this object. Returns an array of length 0 if the
-     * underlying executable takes no parameters.
-     * Note that the constructors of some inner classes
-     * may have an implicitly declared parameter in addition to
-     * explicitly declared ones.
+     * Returns an array of {@code Type} objects that represent the
+     * formal parameter types, in declaration order, of the executable
+     * represented by this object. An array of length 0 is returned if the
+     * underlying executable takes no parameters.  Note that the
+     * constructors of some inner classes may have an implicitly
+     * declared parameter in addition to explicitly declared ones.
+     * Also note that as a <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">modeling
+     * artifact</a>, the number of returned parameters can differ
+     * depending on whether or not generic information is present. If
+     * generic information is present, only parameters explicitly
+     * present in the source will be returned; if generic information
+     * is not present, implicit and synthetic parameters may be
+     * returned as well.
      *
      * <p>If a formal parameter type is a parameterized type,
      * the {@code Type} object returned for it must accurately reflect
@@ -340,19 +347,17 @@ Type[] getAllGenericParameterTypes() {
     }
 
     /**
-     * Returns an array of {@code Parameter} objects that represent
+     * {@return an array of {@code Parameter} objects representing
      * all the parameters to the underlying executable represented by
-     * this object.  Returns an array of length 0 if the executable
+     * this object} An array of length 0 is returned if the executable
      * has no parameters.
      *
      * <p>The parameters of the underlying executable do not necessarily
      * have unique names, or names that are legal identifiers in the
-     * Java programming language (JLS 3.8).
+     * Java programming language (JLS {@jls 3.8}).
      *
      * @throws MalformedParametersException if the class file contains
      * a MethodParameters attribute that is improperly formatted.
-     * @return an array of {@code Parameter} objects representing all
-     * the parameters to the executable this object represents.
      */
     public Parameter[] getParameters() {
         // TODO: This may eventually need to be guarded by security
@@ -492,19 +497,14 @@ public Type[] getGenericExceptionTypes() {
     }
 
     /**
-     * Returns a string describing this {@code Executable}, including
-     * any type parameters.
-     * @return a string describing this {@code Executable}, including
-     * any type parameters
+     * {@return a string describing this {@code Executable}, including
+     * any type parameters}
      */
     public abstract String toGenericString();
 
     /**
-     * Returns {@code true} if this executable was declared to take a
-     * variable number of arguments; returns {@code false} otherwise.
-     *
-     * @return {@code true} if an only if this executable was declared
-     * to take a variable number of arguments.
+     * {@return {@code true} if this executable was declared to take a
+     * variable number of arguments; returns {@code false} otherwise}
      */
     public boolean isVarArgs()  {
         return (getModifiers() & Modifier.VARARGS) != 0;
@@ -672,7 +672,7 @@ AnnotatedType getAnnotatedReturnType0(Type returnType) {
      * by this {@code Executable} object.
      *
      * The receiver type of a method/constructor is available only if the
-     * method/constructor has a receiver parameter (JLS 8.4.1). If this {@code
+     * method/constructor has a receiver parameter (JLS {@jls 8.4.1}). If this {@code
      * Executable} object <em>represents an instance method or represents a
      * constructor of an inner member class</em>, and the
      * method/constructor <em>either</em> has no receiver parameter or has a

src/java.base/share/classes/java/lang/reflect/Parameter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2021, 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
@@ -145,19 +145,20 @@ public String toString() {
     }
 
     /**
-     * Return the {@code Executable} which declares this parameter.
-     *
-     * @return The {@code Executable} declaring this parameter.
+     * {@return the {@code Executable} declaring this parameter}
      */
     public Executable getDeclaringExecutable() {
         return executable;
     }
 
     /**
-     * Get the modifier flags for this the parameter represented by
-     * this {@code Parameter} object.
+     * {@return the Java language {@linkplain Modifier modifiers} for
+     * the parameter represented by this object}
      *
-     * @return The modifier flags for this parameter.
+     * @jls 8.4.1 Formal Parameters
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      */
     public int getModifiers() {
         return modifiers;

src/java.base/share/classes/java/lang/reflect/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, 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
@@ -26,23 +26,73 @@
 /**
  * Provides classes and interfaces for obtaining reflective information about
  * classes and objects.  Reflection allows programmatic access to information
- * about the fields, methods and constructors of loaded classes, and the use
+ * about the fields, methods, and constructors of loaded classes, and the use
  * of reflected fields, methods, and constructors to operate on their underlying
  * counterparts, within encapsulation and security restrictions.
  *
- * <p>{@code AccessibleObject} allows suppression of access checks if
- * the necessary {@code ReflectPermission} is available.
- *
- * <p>{@code Array} provides static methods to dynamically create and
- * access arrays.
- *
  * <p>Classes in this package, along with {@code java.lang.Class}
  * accommodate applications such as debuggers, interpreters, object
  * inspectors, class browsers, and services such as Object
  * Serialization and JavaBeans that need access to either the public
  * members of a target object (based on its runtime class) or the
  * members declared by a given class.
  *
+ * <p>{@link AccessibleObject} allows suppression of access checks if
+ * the necessary {@link ReflectPermission} is available.
+ *
+ * <p>{@link Array} provides static methods to dynamically create and
+ * access arrays.
+ *
+ * <h2><a id="LanguageJvmModel">Java programming language and JVM modeling in core reflection</a></h2>
+ *
+ * The components of core reflection, which include types in this
+ * package as well as {@link java.lang.Class Class}, {@link
+ * java.lang.Package Package}, and {@link java.lang.Module Module},
+ * fundamentally present a JVM model of the entities in question
+ * rather than a Java programming language model.  A Java compiler,
+ * such as {@code javac}, translates Java source code into executable
+ * output that can be run on a JVM, primarily {@code class}
+ * files. Compilers for source languages other than Java can and do
+ * target the JVM as well.
+ *
+ * <p>The translation process, including from Java language sources,
+ * to executable output for the JVM is not a one-to-one
+ * mapping. Structures present in the source language may have no
+ * representation in the output and structures <em>not</em> present in
+ * the source language may be present in the output. The latter are
+ * called <i>synthetic</i> structures. Synthetic structures can
+ * include {@linkplain Method#isSynthetic() methods}, {@linkplain
+ * Field#isSynthetic() fields}, {@linkplain Parameter#isSynthetic()
+ * parameters}, {@linkplain Class#isSynthetic() classes and
+ * interfaces}. One particular kind of synthetic method is a
+ * {@linkplain Method#isBridge() bridge method}. It is possible a
+ * synthetic structure may not be marked as such. In particular, not
+ * all {@code class} file versions support marking a parameter as
+ * synthetic. A source language compiler generally has multiple ways
+ * to translate a source program into a {@code class} file
+ * representation. The translation may also depend on the version of
+ * the {@code class} file format being targeted as different {@code
+ * class} file versions have different capabilities and features. In
+ * some cases the modifiers present in the {@code class} file
+ * representation may differ from the modifiers on the originating
+ * element in the source language, including {@link Modifier#FINAL
+ * final} on a {@linkplain Parameter#getModifiers() parameter} and
+ * {@code protected}, {@code private}, and {@code static} on
+ * {@linkplain java.lang.Class#getModifiers() classes and interfaces}.
+ *
+ * <p>Besides differences in structural representation between the
+ * source language and the JVM representation, core reflection also
+ * exposes runtime specific information. For example, the {@linkplain
+ * java.lang.Class#getClassLoader() class loaders} and {@linkplain
+ * java.lang.Class#getProtectionDomain() protection domains} of a
+ * {@code Class} are runtime concepts without a direct analogue in
+ * source code.
+ *
+ * @jls 13.1 The Form of a Binary
+ * @jvms 1.2 The Java Virtual Machine
+ * @jvms 4.7.8 The Synthetic Attribute
+ * @jvms 5.3.1 Loading Using the Bootstrap Class Loader
+ * @jvms 5.3.2 Loading Using a User-defined Class Loader
  * @since 1.1
  * @revised 9
  */