8265174: Update Class.getDeclaredMethods to discuss synthetic and bridge methods

Reviewed-by: jfranck

Author: jddarcy

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

@@ -784,6 +784,9 @@ public boolean isAnnotation() {
      *
      * @jls 13.1 The Form of a Binary
      * @jvms 4.1 The {@code ClassFile} Structure
+     * @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.5
      */
     public boolean isSynthetic() {
@@ -2402,6 +2405,10 @@ public RecordComponent[] getRecordComponents() {
      * declared methods of the class or interface represented by this {@code
      * Class} object, including public, protected, default (package)
      * access, and private methods, but excluding inherited methods.
+     * The declared methods may include methods <em>not</em> in the
+     * source of the class or interface, including {@linkplain
+     * Method#isBridge bridge methods} and other {@linkplain
+     * Executable#isSynthetic synthetic} methods added by compilers.
      *
      * <p> If this {@code Class} object represents a class or interface that
      * has multiple declared methods with the same name and parameter types,
@@ -2446,6 +2453,9 @@ public RecordComponent[] getRecordComponents() {
      *
      * @jls 8.2 Class Members
      * @jls 8.4 Method Declarations
+     * @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
      */
     @CallerSensitive

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

@@ -515,6 +515,9 @@ public boolean isVarArgs() {
      * @jls 13.1 The Form of a Binary
      * @jvms 4.6 Methods
      * @since 1.5
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      */
     @Override
     public boolean isSynthetic() {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -226,6 +226,9 @@ public boolean isEnumConstant() {
      * @return true if and only if this field is a synthetic
      * field as defined by the Java Language Specification.
      * @since 1.5
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      */
     public boolean isSynthetic() {
         return Modifier.isSynthetic(getModifiers());

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

@@ -607,6 +607,9 @@ public Object invoke(Object obj, Object... args)
      * @jls 8.4.8.3 Requirements in Overriding and Hiding
      * @jls 15.12.4.5 Create Frame, Synchronize, Transfer Control
      * @jvms 4.6 Methods
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      */
     public boolean isBridge() {
         return (getModifiers() & Modifier.BRIDGE) != 0;
@@ -626,6 +629,9 @@ public boolean isVarArgs() {
      * {@inheritDoc}
      * @jls 13.1 The Form of a Binary
      * @jvms 4.6 Methods
+     * @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.5
      */
     @Override

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

@@ -257,10 +257,13 @@ public boolean isImplicit() {
      * nor explicitly declared in source code; returns {@code false}
      * otherwise.
      *
-     * @jls 13.1 The Form of a Binary
      * @return true if and only if this parameter is a synthetic
      * construct as defined by
      * <cite>The Java Language Specification</cite>.
+     * @jls 13.1 The Form of a Binary
+     * @see <a
+     * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
+     * programming language and JVM modeling in core reflection</a>
      */
     public boolean isSynthetic() {
         return Modifier.isSynthetic(getModifiers());