Review Request: JDK-8240242: improve the javadoc for Lookup::dropLookupModes w.r.t. dropping UNCONDITIONAL

[Chris Hegarty]

This looks good to me Mandy.

Thanks,
-Chris.

> On 10 Mar 2020, at 18:27, Mandy Chung <mandy.chung at oracle.com> wrote:
> 
> Hi Chris,
> 
> Below is the revised patch per your suggestion.  I made some minor fixes in the method name shown in the "Access modes" section as well.
> 
> Mandy
> 
> diff --git a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
> --- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
> +++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
> @@ -740,11 +740,11 @@
>       * The table below shows the access modes of a {@code Lookup} produced by
>       * any of the following factory or transformation methods:
>       * <ul>
> -     * <li>{@link #lookup() MethodHandles.lookup()}</li>
> -     * <li>{@link #publicLookup() MethodHandles.publicLookup()}</li>
> -     * <li>{@link #privateLookupIn(Class, Lookup) MethodHandles.privateLookupIn}</li>
> -     * <li>{@link Lookup#in}</li>
> -     * <li>{@link Lookup#dropLookupMode(int)}</li>
> +     * <li>{@link #lookup() MethodHandles::lookup}</li>
> +     * <li>{@link #publicLookup() MethodHandles::publicLookup}</li>
> +     * <li>{@link #privateLookupIn(Class, Lookup) MethodHandles::privateLookupIn}</li>
> +     * <li>{@link Lookup#in Lookup::in}</li>
> +     * <li>{@link Lookup#dropLookupMode(int) Lookup::dropLookupMode}</li>
>       * </ul>
>       *
>       * <table class="striped">
> @@ -1524,14 +1524,22 @@
>           * Creates a lookup on the same lookup class which this lookup object
>           * finds members, but with a lookup mode that has lost the given lookup mode.
>           * The lookup mode to drop is one of {@link #PUBLIC PUBLIC}, {@link #MODULE
> -         * MODULE}, {@link #PACKAGE PACKAGE}, {@link #PROTECTED PROTECTED} or {@link #PRIVATE PRIVATE}.
> -         * {@link #PROTECTED PROTECTED} is always
> -         * dropped and so the resulting lookup mode will never have this access capability.
> -         * When dropping {@code PACKAGE} then the resulting lookup will not have {@code PACKAGE}
> -         * or {@code PRIVATE} access. When dropping {@code MODULE} then the resulting lookup will
> -         * not have {@code MODULE}, {@code PACKAGE}, or {@code PRIVATE} access. If {@code PUBLIC}
> -         * is dropped then the resulting lookup has no access. If {@code UNCONDITIONAL}
> -         * is dropped then the resulting lookup has no access.
> +         * MODULE}, {@link #PACKAGE PACKAGE}, {@link #PROTECTED PROTECTED},
> +         * {@link #PRIVATE PRIVATE}, or {@link #UNCONDITIONAL UNCONDITIONAL}.
> +         *
> +         * <p> If this lookup is a {@linkplain MethodHandles#publicLookup() public lookup},
> +         * this lookup has {@code UNCONDITIONAL} mode set and it has no other mode set.
> +         * When dropping {@code UNCONDITIONAL} on a public lookup then the resulting
> +         * lookup has no access.
> +         *
> +         * <p> If this lookup is not a public lookup, then the following applies
> +         * regardless of its {@linkplain #lookupModes() lookup modes}.
> +         * {@link #PROTECTED PROTECTED} is always dropped and so the resulting lookup
> +         * mode will never have this access capability. When dropping {@code PACKAGE}
> +         * then the resulting lookup will not have {@code PACKAGE} or {@code PRIVATE}
> +         * access. When dropping {@code MODULE} then the resulting lookup will not
> +         * have {@code MODULE}, {@code PACKAGE}, or {@code PRIVATE} access.
> +         * When dropping {@code PUBLIC} then the resulting lookup has no access.
>           *
>           * @apiNote
>           * A lookup with {@code PACKAGE} but not {@code PRIVATE} mode can safely