src/java.base/share/classes/java/lang/invoke/MethodHandles.java

*** 129,139 ****
       * Returns a {@link Lookup lookup object} which is trusted minimally.
       * The lookup has the {@code PUBLIC} and {@code UNCONDITIONAL} modes.
       * It can only be used to create method handles to public members of
       * public classes in packages that are exported unconditionally.
       * <p>
!      * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}
       * of this lookup object will be {@link java.lang.Object}.
       *
       * @apiNote The use of Object is conventional, and because the lookup modes are
       * limited, there is no special access provided to the internals of Object, its package
       * or its module. Consequently, the lookup context of this lookup object will be the
--- 129,139 ----
       * Returns a {@link Lookup lookup object} which is trusted minimally.
       * The lookup has the {@code PUBLIC} and {@code UNCONDITIONAL} modes.
       * It can only be used to create method handles to public members of
       * public classes in packages that are exported unconditionally.
       * <p>
!      * As a matter of pure convention, the {@linkplain Lookup#lookupClass() lookup class}
       * of this lookup object will be {@link java.lang.Object}.
       *
       * @apiNote The use of Object is conventional, and because the lookup modes are
       * limited, there is no special access provided to the internals of Object, its package
       * or its module. Consequently, the lookup context of this lookup object will be the
*** 257,270 ****
       * Method handles do not perform
       * access checks when they are called, but rather when they are created.
       * Therefore, method handle access
       * restrictions must be enforced when a method handle is created.
       * The caller class against which those restrictions are enforced
!      * is known as the {@linkplain #lookupClass lookup class}.
       * <p>
       * A lookup class which needs to create method handles will call
!      * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
       * When the {@code Lookup} factory object is created, the identity of the lookup class is
       * determined, and securely stored in the {@code Lookup} object.
       * The lookup class (or its delegates) may then use factory methods
       * on the {@code Lookup} object to create method handles for access-checked members.
       * This includes all methods, constructors, and fields which are allowed to the lookup class,
--- 257,270 ----
       * Method handles do not perform
       * access checks when they are called, but rather when they are created.
       * Therefore, method handle access
       * restrictions must be enforced when a method handle is created.
       * The caller class against which those restrictions are enforced
!      * is known as the {@linkplain #lookupClass() lookup class}.
       * <p>
       * A lookup class which needs to create method handles will call
!      * {@link MethodHandles#lookup() MethodHandles.lookup} to create a factory for itself.
       * When the {@code Lookup} factory object is created, the identity of the lookup class is
       * determined, and securely stored in the {@code Lookup} object.
       * The lookup class (or its delegates) may then use factory methods
       * on the {@code Lookup} object to create method handles for access-checked members.
       * This includes all methods, constructors, and fields which are allowed to the lookup class,
*** 774,784 ****
          }
  
          /**
           * Creates a lookup on the specified new lookup class.
           * The resulting object will report the specified
!          * class as its own {@link #lookupClass lookupClass}.
           * <p>
           * However, the resulting {@code Lookup} object is guaranteed
           * to have no more access capabilities than the original.
           * In particular, access capabilities can be lost as follows:<ul>
           * <li>If the old lookup class is in a {@link Module#isNamed() named} module, and
--- 774,784 ----
          }
  
          /**
           * Creates a lookup on the specified new lookup class.
           * The resulting object will report the specified
!          * class as its own {@link #lookupClass() lookupClass}.
           * <p>
           * However, the resulting {@code Lookup} object is guaranteed
           * to have no more access capabilities than the original.
           * In particular, access capabilities can be lost as follows:<ul>
           * <li>If the old lookup class is in a {@link Module#isNamed() named} module, and
*** 4600,4610 ****
       * <li>At this point, every init function parameter list is effectively identical to the external parameter list {@code (A...)},
       * but some lists may be shorter. For every init function with a short parameter list, pad out the end of the list.
       * <li>At this point, every non-init function parameter list is effectively identical to the internal parameter
       * list {@code (V... A...)}, but some lists may be shorter. For every non-init function with a short parameter list,
       * pad out the end of the list.
!      * <li>Argument lists are padded out by {@linkplain #dropArgumentsToMatch dropping unused trailing arguments}.
       * </ol>
       * <p>
       * <em>Final observations.</em><ol type="a">
       * <li>After these steps, all clauses have been adjusted by supplying omitted functions and arguments.
       * <li>All init functions have a common parameter type list {@code (A...)}, which the final loop handle will also have.
--- 4600,4610 ----
       * <li>At this point, every init function parameter list is effectively identical to the external parameter list {@code (A...)},
       * but some lists may be shorter. For every init function with a short parameter list, pad out the end of the list.
       * <li>At this point, every non-init function parameter list is effectively identical to the internal parameter
       * list {@code (V... A...)}, but some lists may be shorter. For every non-init function with a short parameter list,
       * pad out the end of the list.
!      * <li>Argument lists are padded out by {@linkplain #dropArgumentsToMatch(MethodHandle, int, List, int) dropping unused trailing arguments}.
       * </ol>
       * <p>
       * <em>Final observations.</em><ol type="a">
       * <li>After these steps, all clauses have been adjusted by supplying omitted functions and arguments.
       * <li>All init functions have a common parameter type list {@code (A...)}, which the final loop handle will also have.
*** 4695,4705 ****
       *   }
       * }
       * }</pre></blockquote>
       * Note that the parameter type lists {@code (V...)} and {@code (A...)} have been expanded
       * to their full length, even though individual clause functions may neglect to take them all.
!      * As noted above, missing parameters are filled in as if by {@link #dropArgumentsToMatch}.
       *
       * @apiNote Example:
       * <blockquote><pre>{@code
       * // iterative implementation of the factorial function as a loop handle
       * static int one(int k) { return 1; }
--- 4695,4705 ----
       *   }
       * }
       * }</pre></blockquote>
       * Note that the parameter type lists {@code (V...)} and {@code (A...)} have been expanded
       * to their full length, even though individual clause functions may neglect to take them all.
!      * As noted above, missing parameters are filled in as if by {@link #dropArgumentsToMatch(MethodHandle, int, List, int)}.
       *
       * @apiNote Example:
       * <blockquote><pre>{@code
       * // iterative implementation of the factorial function as a loop handle
       * static int one(int k) { return 1; }