8024438: JSR 292 API specification maintenance for JDK 8
authorjrose
Sat, 05 Oct 2013 05:30:40 -0700
changeset 20535 cc85c8626435
parent 20534 da86f7904e6d
child 20536 2e22d22c52ed
8024438: JSR 292 API specification maintenance for JDK 8 Summary: add wildcard to unreflectConstructor, various clarifications and minor edits Reviewed-by: mchung, darcy, twisti
jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java
jdk/src/share/classes/java/lang/invoke/CallSite.java
jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java
jdk/src/share/classes/java/lang/invoke/LambdaForm.java
jdk/src/share/classes/java/lang/invoke/MethodHandle.java
jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java
jdk/src/share/classes/java/lang/invoke/MethodHandles.java
jdk/src/share/classes/java/lang/invoke/MethodType.java
jdk/src/share/classes/java/lang/invoke/MutableCallSite.java
jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
jdk/src/share/classes/sun/invoke/WrapperInstance.java
jdk/src/share/classes/sun/invoke/util/VerifyAccess.java
jdk/src/share/classes/sun/invoke/util/VerifyType.java
jdk/test/java/lang/invoke/AccessControlTest.java
jdk/test/java/lang/invoke/MethodHandlesTest.java
jdk/test/java/lang/invoke/RevealDirectTest.java
--- a/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java	Sat Oct 05 05:30:40 2013 -0700
@@ -529,18 +529,18 @@
          * A concrete BMH species adheres to the following schema:
          *
          * <pre>
-         * class Species_<<types>> extends BoundMethodHandle {
-         *     <<fields>>
-         *     final SpeciesData speciesData() { return SpeciesData.get("<<types>>"); }
+         * class Species_[[types]] extends BoundMethodHandle {
+         *     [[fields]]
+         *     final SpeciesData speciesData() { return SpeciesData.get("[[types]]"); }
          * }
          * </pre>
          *
-         * The {@code <<types>>} signature is precisely the string that is passed to this
+         * The {@code [[types]]} signature is precisely the string that is passed to this
          * method.
          *
-         * The {@code <<fields>>} section consists of one field definition per character in
+         * The {@code [[fields]]} section consists of one field definition per character in
          * the type signature, adhering to the naming schema described in the definition of
-         * {@link #makeFieldName()}.
+         * {@link #makeFieldName}.
          *
          * For example, a concrete BMH species for two reference and one integral bound values
          * would have the following shape:
@@ -822,7 +822,7 @@
          * {@code <init>}. To avoid this, we add an indirection by invoking {@code <init>} through
          * {@link MethodHandle#linkToSpecial}.
          *
-         * The last {@link LambdaForm#Name Name} in the argument's form is expected to be the {@code void}
+         * The last {@link LambdaForm.Name Name} in the argument's form is expected to be the {@code void}
          * result of the {@code <init>} invocation. This entry is replaced.
          */
         private static MethodHandle linkConstructor(MethodHandle cmh) {
--- a/jdk/src/share/classes/java/lang/invoke/CallSite.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/CallSite.java	Sat Oct 05 05:30:40 2013 -0700
@@ -60,7 +60,7 @@
  * <p>
  * Here is a sample use of call sites and bootstrap methods which links every
  * dynamic call site to print its arguments:
-<blockquote><pre><!-- see indy-demo/src/PrintArgsDemo.java -->
+<blockquote><pre>{@code
 static void test() throws Throwable {
     // THE FOLLOWING LINE IS PSEUDOCODE FOR A JVM INSTRUCTION
     InvokeDynamic[#bootstrapDynamic].baz("baz arg", 2, 3.14);
@@ -79,7 +79,7 @@
   // ignore caller and name, but match the type:
   return new ConstantCallSite(printArgs.asType(type));
 }
-</pre></blockquote>
+}</pre></blockquote>
  * @author John Rose, JSR 292 EG
  */
 abstract
@@ -199,12 +199,12 @@
      * which has been linked to this call site.
      * <p>
      * This method is equivalent to the following code:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * MethodHandle getTarget, invoker, result;
      * getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
      * invoker = MethodHandles.exactInvoker(this.type());
      * result = MethodHandles.foldArguments(invoker, getTarget)
-     * </pre></blockquote>
+     * }</pre></blockquote>
      *
      * @return a method handle which always invokes this call site's current target
      */
--- a/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java	Sat Oct 05 05:30:40 2013 -0700
@@ -242,9 +242,6 @@
 
     /**
      * Extract the MemberName of a newly-defined method.
-     *
-     * @param classFile
-     * @return
      */
     private MemberName loadMethod(byte[] classFile) {
         Class<?> invokerClass = loadAndInitializeInvokerClass(classFile, cpPatches(classFile));
@@ -253,10 +250,6 @@
 
     /**
      * Define a given class as anonymous class in the runtime system.
-     *
-     * @param classBytes
-     * @param patches
-     * @return
      */
     private static Class<?> loadAndInitializeInvokerClass(byte[] classBytes, Object[] patches) {
         Class<?> invokerClass = UNSAFE.defineAnonymousClass(HOST_CLASS, classBytes, patches);
@@ -264,14 +257,6 @@
         return invokerClass;
     }
 
-    /**
-     * TODO
-     *
-     * @param invokerClass
-     * @param name
-     * @param type
-     * @return
-     */
     private static MemberName resolveInvokerMember(Class<?> invokerClass, String name, MethodType type) {
         MemberName member = new MemberName(invokerClass, name, type, REF_invokeStatic);
         //System.out.println("resolveInvokerMember => "+member);
@@ -499,10 +484,6 @@
 
     /**
      * Generate customized bytecode for a given LambdaForm.
-     *
-     * @param form
-     * @param invokerType
-     * @return
      */
     static MemberName generateCustomizedCode(LambdaForm form, MethodType invokerType) {
         InvokerBytecodeGenerator g = new InvokerBytecodeGenerator("MH", form, invokerType);
@@ -565,8 +546,6 @@
 
     /**
      * Emit an invoke for the given name.
-     *
-     * @param name
      */
     void emitInvoke(Name name) {
         if (true) {
@@ -645,8 +624,6 @@
 
     /**
      * Emit an invoke for the given name, using the MemberName directly.
-     *
-     * @param name
      */
     void emitStaticInvoke(MemberName member, Name name) {
         assert(member.equals(name.function.member()));
@@ -690,9 +667,6 @@
 
     /**
      * Check if MemberName is a call to MethodHandleImpl.selectAlternative.
-     *
-     * @param member
-     * @return true if member is a call to MethodHandleImpl.selectAlternative
      */
     private boolean isSelectAlternative(MemberName member) {
         return member != null &&
@@ -704,14 +678,12 @@
      * Emit bytecode for the selectAlternative idiom.
      *
      * The pattern looks like (Cf. MethodHandleImpl.makeGuardWithTest):
-     *
+     * <blockquote><pre>{@code
      *   Lambda(a0:L,a1:I)=>{
      *     t2:I=foo.test(a1:I);
      *     t3:L=MethodHandleImpl.selectAlternative(t2:I,(MethodHandle(int)int),(MethodHandle(int)int));
      *     t4:I=MethodHandle.invokeBasic(t3:L,a1:I);t4:I}
-     *
-     * @param selectAlternativeName
-     * @param invokeBasicName
+     * }</pre></blockquote>
      */
     private void emitSelectAlternative(Name selectAlternativeName, Name invokeBasicName) {
         MethodType type = selectAlternativeName.function.methodType();
@@ -750,11 +722,6 @@
         mv.visitLabel(L_done);
     }
 
-    /**
-     *
-     * @param name
-     * @param paramIndex
-     */
     private void emitPushArgument(Name name, int paramIndex) {
         Object arg = name.arguments[paramIndex];
         char ptype = name.function.parameterType(paramIndex);
@@ -923,9 +890,6 @@
 
     /**
      * Generate bytecode for a LambdaForm.vmentry which calls interpretWithArguments.
-     *
-     * @param sig
-     * @return
      */
     static MemberName generateLambdaFormInterpreterEntryPoint(String sig) {
         assert(LambdaForm.isValidSignature(sig));
@@ -993,10 +957,6 @@
 
     /**
      * Generate bytecode for a NamedFunction invoker.
-     *
-     * @param srcType
-     * @param dstType
-     * @return
      */
     static MemberName generateNamedFunctionInvoker(MethodTypeForm typeForm) {
         MethodType invokerType = LambdaForm.NamedFunction.INVOKER_METHOD_TYPE;
--- a/jdk/src/share/classes/java/lang/invoke/LambdaForm.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/LambdaForm.java	Sat Oct 05 05:30:40 2013 -0700
@@ -50,7 +50,7 @@
  * The result of the lambda is defined as one of the names, often the last one.
  * <p>
  * Here is an approximate grammar:
- * <pre>
+ * <blockquote><pre>{@code
  * LambdaForm = "(" ArgName* ")=>{" TempName* Result "}"
  * ArgName = "a" N ":" T
  * TempName = "t" N ":" T "=" Function "(" Argument* ");"
@@ -60,7 +60,7 @@
  * NameRef = "a" N | "t" N
  * N = (any whole number)
  * T = "L" | "I" | "J" | "F" | "D" | "V"
- * </pre>
+ * }</pre></blockquote>
  * Names are numbered consecutively from left to right starting at zero.
  * (The letters are merely a taste of syntax sugar.)
  * Thus, the first temporary (if any) is always numbered N (where N=arity).
@@ -69,7 +69,7 @@
  * A lambda has a void result if and only if its result index is -1.
  * If a temporary has the type "V", it cannot be the subject of a NameRef,
  * even though possesses a number.
- * Note that all reference types are erased to "L", which stands for {@code Object).
+ * Note that all reference types are erased to "L", which stands for {@code Object}.
  * All subword types (boolean, byte, short, char) are erased to "I" which is {@code int}.
  * The other types stand for the usual primitive types.
  * <p>
@@ -89,7 +89,7 @@
  * encoded by using temporary expressions which call type-transformed identity functions.
  * <p>
  * Examples:
- * <pre>
+ * <blockquote><pre>{@code
  * (a0:J)=>{ a0 }
  *     == identity(long)
  * (a0:I)=>{ t1:V = System.out#println(a0); void }
@@ -113,7 +113,7 @@
  * (a0:L, a1:L)=>{ t2:L = BoundMethodHandle#argument(a0);
  *                 t3:L = Class#cast(t2,a1); t3 }
  *     == invoker for identity method handle which performs cast
- * </pre>
+ * }</pre></blockquote>
  * <p>
  * @author John Rose, JSR 292 EG
  */
@@ -1441,8 +1441,6 @@
          * Does this Name precede the given binding node in some canonical order?
          * This predicate is used to order data bindings (via insertion sort)
          * with some stability.
-         * @param binding
-         * @return
          */
         boolean isSiblingBindingBefore(Name binding) {
             assert(!binding.isParam());
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandle.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandle.java	Sat Oct 05 05:30:40 2013 -0700
@@ -292,7 +292,7 @@
  * generates a single invokevirtual instruction with
  * the symbolic type descriptor indicated in the following comment.
  * In these examples, the helper method {@code assertEquals} is assumed to
- * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals }
+ * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals}
  * on its arguments, and asserts that the result is true.
  *
  * <h1>Exceptions</h1>
@@ -575,10 +575,10 @@
     /*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
 
     /**
-     * Performs a variable arity invocation, passing the arguments in the given array
+     * Performs a variable arity invocation, passing the arguments in the given list
      * to the method handle, as if via an inexact {@link #invoke invoke} from a call site
      * which mentions only the type {@code Object}, and whose arity is the length
-     * of the argument array.
+     * of the argument list.
      * <p>
      * Specifically, execution proceeds as if by the following steps,
      * although the methods are not guaranteed to be called if the JVM
@@ -608,10 +608,10 @@
      * or forced to null if the return type is void.
      * <p>
      * This call is equivalent to the following code:
-     * <p><blockquote><pre>
+     * <p><blockquote><pre>{@code
      * MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
      * Object result = invoker.invokeExact(this, arguments);
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * Unlike the signature polymorphic methods {@code invokeExact} and {@code invoke},
      * {@code invokeWithArguments} can be accessed normally via the Core Reflection API and JNI.
@@ -644,7 +644,7 @@
      * <p>
      * This method is also equivalent to the following code:
      * <p><blockquote><pre>
-     * {@link #invokeWithArguments(Object...) invokeWithArguments}(arguments.toArray())
+     * {@link #invokeWithArguments(Object...) invokeWithArguments}{@code(arguments.toArray())}
      * </pre></blockquote>
      *
      * @param arguments the arguments to pass to the target
@@ -1272,9 +1272,9 @@
      * starting with the string {@code "MethodHandle"} and
      * ending with the string representation of the method handle's type.
      * In other words, this method returns a string equal to the value of:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * "MethodHandle" + type().toString()
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * (<em>Note:</em>  Future releases of this API may add further information
      * to the string representation.
@@ -1485,7 +1485,6 @@
      * Threads may continue running the old form indefinitely,
      * but it is likely that the new one will be preferred for new executions.
      * Use with discretion.
-     * @param newForm
      */
     /*non-public*/
     void updateForm(LambdaForm newForm) {
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java	Sat Oct 05 05:30:40 2013 -0700
@@ -32,9 +32,10 @@
 import static java.lang.invoke.MethodHandleStatics.*;
 
 /**
- * A symbolic reference obtained by cracking a method handle into its consitutent symbolic parts.
+ * A symbolic reference obtained by cracking a direct method handle
+ * into its consitutent symbolic parts.
  * To crack a direct method handle, call {@link Lookup#revealDirect Lookup.revealDirect}.
- * <p>
+ * <h1><a name="directmh"></a>Direct Method Handles</h1>
  * A <em>direct method handle</em> represents a method, constructor, or field without
  * any intervening argument bindings or other transformations.
  * The method, constructor, or field referred to by a direct method handle is called
@@ -56,7 +57,9 @@
  *     or {@link Lookup#unreflectSetter Lookup.unreflectSetter}
  *     to convert a {@link Field} into a method handle.
  * </ul>
- * In all of these cases, it is possible to crack the resulting direct method handle
+ *
+ * <h1>Restrictions on Cracking</h1>
+ * Given a suitable {@code Lookup} object, it is possible to crack any direct method handle
  * to recover a symbolic reference for the underlying method, constructor, or field.
  * Cracking must be done via a {@code Lookup} object equivalent to that which created
  * the target method handle, or which has enough access permissions to recreate
@@ -202,7 +205,7 @@
      * @return the Java language modifiers for underlying member,
      *         or -1 if the member cannot be accessed
      * @see Modifier
-     * @see reflectAs
+     * @see #reflectAs
      */
     public int getModifiers();
 
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandles.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandles.java	Sat Oct 05 05:30:40 2013 -0700
@@ -49,7 +49,6 @@
  * <li>Lookup methods which help create method handles for methods and fields.
  * <li>Combinator methods, which combine or transform pre-existing method handles into new ones.
  * <li>Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.
- * <li>Wrapper methods which can convert between method handles and interface types.
  * </ul>
  * <p>
  * @author John Rose, JSR 292 EG
@@ -66,12 +65,25 @@
     //// Method handle creation from ordinary methods.
 
     /**
-     * Returns a {@link Lookup lookup object} on the caller,
-     * which has the capability to access any method handle that the caller has access to,
-     * including direct method handles to private fields and methods.
+     * Returns a {@link Lookup lookup object} with
+     * full capabilities to emulate all supported bytecode behaviors of the caller.
+     * These capabilities include <a href="MethodHandles.Lookup.html#privacc">private access</a> to the caller.
+     * Factory methods on the lookup object can create
+     * <a href="MethodHandleInfo.html#directmh">direct method handles</a>
+     * for any member that the caller has access to via bytecodes,
+     * including protected and private fields and methods.
      * This lookup object is a <em>capability</em> which may be delegated to trusted agents.
      * Do not store it in place where untrusted code can access it.
-     * @return a lookup object for the caller of this method
+     * <p>
+     * This method is caller sensitive, which means that it may return different
+     * values to different callers.
+     * <p>
+     * For any given caller class {@code C}, the lookup object returned by this call
+     * has equivalent capabilities to any lookup object
+     * supplied by the JVM to the bootstrap method of an
+     * <a href="package-summary.html#indyinsn">invokedynamic instruction</a>
+     * executing in the same caller class {@code C}.
+     * @return a lookup object for the caller of this method, with private access
      */
     @CallerSensitive
     public static Lookup lookup() {
@@ -85,9 +97,11 @@
      * <p>
      * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}
      * of this lookup object will be {@link java.lang.Object}.
-     * <p>
+     *
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
      * The lookup class can be changed to any other class {@code C} using an expression of the form
-     * {@linkplain Lookup#in <code>publicLookup().in(C.class)</code>}.
+     * {@link Lookup#in publicLookup().in(C.class)}.
      * Since all classes have equal access to public names,
      * such a change would confer no new access rights.
      * A public lookup object is always subject to
@@ -101,7 +115,8 @@
     }
 
     /**
-     * Performs an unchecked "crack" of a direct method handle.
+     * Performs an unchecked "crack" of a
+     * <a href="MethodHandleInfo.html#directmh">direct method handle</a>.
      * The result is as if the user had obtained a lookup object capable enough
      * to crack the target method handle, called
      * {@link java.lang.invoke.MethodHandles.Lookup#revealDirect Lookup.revealDirect}
@@ -154,10 +169,17 @@
      * <h1><a name="lookups"></a>Lookup Factory Methods</h1>
      * The factory methods on a {@code Lookup} object correspond to all major
      * use cases for methods, constructors, and fields.
+     * Each method handle created by a factory method is the functional
+     * equivalent of a particular <em>bytecode behavior</em>.
+     * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
      * Here is a summary of the correspondence between these factory methods and
      * the behavior the resulting method handles:
      * <table border=1 cellpadding=5 summary="lookup method behaviors">
-     * <tr><th>lookup expression</th><th>member</th><th>behavior</th></tr>
+     * <tr>
+     *     <th><a name="equiv"></a>lookup expression</th>
+     *     <th>member</th>
+     *     <th>bytecode behavior</th>
+     * </tr>
      * <tr>
      *     <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
      *     <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
@@ -233,10 +255,12 @@
      * In cases where the given member is of variable arity (i.e., a method or constructor)
      * the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}.
      * In all other cases, the returned method handle will be of fixed arity.
-     * <p>
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
      * The equivalence between looked-up method handles and underlying
-     * class members can break down in a few ways:
-     * <ul>
+     * class members and bytecode behaviors
+     * can break down in a few ways:
+     * <ul style="font-size:smaller;">
      * <li>If {@code C} is not symbolically accessible from the lookup class's loader,
      * the lookup can still succeed, even when there is no equivalent
      * Java expression or bytecoded constant.
@@ -280,7 +304,8 @@
      * A lookup can fail, because
      * the containing class is not accessible to the lookup class, or
      * because the desired class member is missing, or because the
-     * desired class member is not accessible to the lookup class.
+     * desired class member is not accessible to the lookup class, or
+     * because the lookup object is not trusted enough to access the member.
      * In any of these cases, a {@code ReflectiveOperationException} will be
      * thrown from the attempted lookup.  The exact class will be one of
      * the following:
@@ -291,14 +316,23 @@
      * </ul>
      * <p>
      * In general, the conditions under which a method handle may be
-     * looked up for a method {@code M} are exactly equivalent to the conditions
-     * under which the lookup class could have compiled and resolved a call to {@code M}.
+     * looked up for a method {@code M} are no more restrictive than the conditions
+     * under which the lookup class could have compiled, verified, and resolved a call to {@code M}.
      * Where the JVM would raise exceptions like {@code NoSuchMethodError},
      * a method handle lookup will generally raise a corresponding
      * checked exception, such as {@code NoSuchMethodException}.
      * And the effect of invoking the method handle resulting from the lookup
-     * is exactly equivalent to executing the compiled and resolved call to {@code M}.
+     * is <a href="MethodHandles.Lookup.html#equiv">exactly equivalent</a>
+     * to executing the compiled, verified, and resolved call to {@code M}.
      * The same point is true of fields and constructors.
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
+     * Access checks only apply to named and reflected methods,
+     * constructors, and fields.
+     * Other method handle creation methods, such as
+     * {@link MethodHandle#asType MethodHandle.asType},
+     * do not require any access checks, and are used
+     * independently of any {@code Lookup} object.
      * <p>
      * If the desired member is {@code protected}, the usual JVM rules apply,
      * including the requirement that the lookup class must be either be in the
@@ -312,6 +346,12 @@
      * (which will necessarily be a superclass of the lookup class)
      * to the lookup class itself.
      * <p>
+     * The JVM imposes a similar requirement on {@code invokespecial} instruction,
+     * that the receiver argument must match both the resolved method <em>and</em>
+     * the current class.  Again, this requirement is enforced by narrowing the
+     * type of the leading parameter to the resulting method handle.
+     * (See the Java Virtual Machine Specification, section 4.10.1.9.)
+     * <p>
      * The JVM represents constructors and static initializer blocks as internal methods
      * with special names ({@code "<init>"} and {@code "<clinit>"}).
      * The internal syntax of invocation instructions allows them to refer to such internal
@@ -331,6 +371,43 @@
      * which can transform a lookup on {@code C.E} into one on any of those other
      * classes, without special elevation of privilege.
      * <p>
+     * The accesses permitted to a given lookup object may be limited,
+     * according to its set of {@link #lookupModes lookupModes},
+     * to a subset of members normally accessible to the lookup class.
+     * For example, the {@link MethodHandles#publicLookup publicLookup}
+     * method produces a lookup object which is only allowed to access
+     * public members in public classes.
+     * The caller sensitive method {@link MethodHandles#lookup lookup}
+     * produces a lookup object with full capabilities relative to
+     * its caller class, to emulate all supported bytecode behaviors.
+     * Also, the {@link Lookup#in Lookup.in} method may produce a lookup object
+     * with fewer access modes than the original lookup object.
+     *
+     * <p style="font-size:smaller;">
+     * <a name="privacc"></a>
+     * <em>Discussion of private access:</em>
+     * We say that a lookup has <em>private access</em>
+     * if its {@linkplain #lookupModes lookup modes}
+     * include the possibility of accessing {@code private} members.
+     * As documented in the relevant methods elsewhere,
+     * only lookups with private access possess the following capabilities:
+     * <ul style="font-size:smaller;">
+     * <li>access private fields, methods, and constructors of the lookup class
+     * <li>create method handles which invoke <a href="MethodHandles.Lookup.html#callsens">caller sensitive</a> methods,
+     *     such as {@code Class.forName}
+     * <li>create method handles which {@link Lookup#findSpecial emulate invokespecial} instructions
+     * <li>avoid <a href="MethodHandles.Lookup.html#secmgr">package access checks</a>
+     *     for classes accessible to the lookup class
+     * <li>create {@link Lookup#in delegated lookup objects} which have private access to other classes
+     *     within the same package member
+     * </ul>
+     * <p style="font-size:smaller;">
+     * Each of these permissions is a consequence of the fact that a lookup object
+     * with private access can be securely traced back to an originating class,
+     * whose <a href="MethodHandles.Lookup.html#equiv">bytecode behaviors</a> and Java language access permissions
+     * can be reliably determined and emulated by method handles.
+     *
+     * <h1><a name="secmgr"></a>Security manager interactions</h1>
      * Although bytecode instructions can only refer to classes in
      * a related class loader, this API can search for methods in any
      * class, as long as a reference to its {@code Class} object is
@@ -343,16 +420,6 @@
      * and the Core Reflection API
      * (as found on {@link java.lang.Class Class}).
      * <p>
-     * Access checks only apply to named and reflected methods,
-     * constructors, and fields.
-     * Other method handle creation methods, such as
-     * {@link MethodHandle#asType MethodHandle.asType},
-     * do not require any access checks, and are done
-     * with static methods of {@link MethodHandles},
-     * independently of any {@code Lookup} object.
-     *
-     * <h1>Security manager interactions</h1>
-     * <a name="secmgr"></a>
      * If a security manager is present, member lookups are subject to
      * additional checks.
      * From one to three calls are made to the security manager.
@@ -365,19 +432,22 @@
      * member is actually defined.
      * The value {@code lookc} is defined as <em>not present</em>
      * if the current lookup object does not have
-     * {@linkplain java.lang.invoke.MethodHandles.Lookup#PRIVATE private access}.
+     * <a href="MethodHandles.Lookup.html#privacc">private access</a>.
      * The calls are made according to the following rules:
      * <ul>
-     * <li>If {@code lookc} is not present, or if its class loader is not
+     * <li><b>Step 1:</b>
+     *     If {@code lookc} is not present, or if its class loader is not
      *     the same as or an ancestor of the class loader of {@code refc},
      *     then {@link SecurityManager#checkPackageAccess
      *     smgr.checkPackageAccess(refcPkg)} is called,
      *     where {@code refcPkg} is the package of {@code refc}.
-     * <li>If the retrieved member is not public and
+     * <li><b>Step 2:</b>
+     *     If the retrieved member is not public and
      *     {@code lookc} is not present, then
      *     {@link SecurityManager#checkPermission smgr.checkPermission}
      *     with {@code RuntimePermission("accessDeclaredMembers")} is called.
-     * <li>If the retrieved member is not public,
+     * <li><b>Step 3:</b>
+     *     If the retrieved member is not public,
      *     and if {@code lookc} is not present,
      *     and if {@code defc} and {@code refc} are different,
      *     then {@link SecurityManager#checkPackageAccess
@@ -408,11 +478,32 @@
      * In cases where the lookup object is
      * {@link MethodHandles#publicLookup() publicLookup()},
      * or some other lookup object without
-     * {@linkplain java.lang.invoke.MethodHandles.Lookup#PRIVATE private access},
+     * <a href="MethodHandles.Lookup.html#privacc">private access</a>,
      * the lookup class is disregarded.
      * In such cases, no caller-sensitive method handle can be created,
      * access is forbidden, and the lookup fails with an
      * {@code IllegalAccessException}.
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
+     * For example, the caller-sensitive method
+     * {@link java.lang.Class#forName(String) Class.forName(x)}
+     * can return varying classes or throw varying exceptions,
+     * depending on the class loader of the class that calls it.
+     * A public lookup of {@code Class.forName} will fail, because
+     * there is no reasonable way to determine its bytecode behavior.
+     * <p style="font-size:smaller;">
+     * If an application caches method handles for broad sharing,
+     * it should use {@code publicLookup()} to create them.
+     * If there is a lookup of {@code Class.forName}, it will fail,
+     * and the application must take appropriate action in that case.
+     * It may be that a later lookup, perhaps during the invocation of a
+     * bootstrap method, can incorporate the specific identity
+     * of the caller, making the method accessible.
+     * <p style="font-size:smaller;">
+     * The function {@code MethodHandles.lookup} is caller sensitive
+     * so that there can be a secure foundation for lookups.
+     * Nearly all other methods in the JSR 292 API rely on lookup
+     * objects to check access requests.
      */
     public static final
     class Lookup {
@@ -639,7 +730,7 @@
          * (Since static methods do not take receivers, there is no
          * additional receiver argument inserted into the method handle type,
          * as there would be with {@link #findVirtual findVirtual} or {@link #findSpecial findSpecial}.)
-         * The method and all its argument types must be accessible to the lookup class.
+         * The method and all its argument types must be accessible to the lookup object.
          * <p>
          * The returned method handle will have
          * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
@@ -679,7 +770,7 @@
          * Produces a method handle for a virtual method.
          * The type of the method handle will be that of the method,
          * with the receiver type (usually {@code refc}) prepended.
-         * The method and all its argument types must be accessible to the lookup class.
+         * The method and all its argument types must be accessible to the lookup object.
          * <p>
          * When called, the handle will treat the first argument as a receiver
          * and dispatch on the receiver's type to determine which method
@@ -696,7 +787,7 @@
          * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
          * the method's variable arity modifier bit ({@code 0x0080}) is set.
          * <p>
-         * Because of the general equivalence between {@code invokevirtual}
+         * Because of the general <a href="MethodHandles.Lookup.html#equiv">equivalence</a> between {@code invokevirtual}
          * instructions and method handles produced by {@code findVirtual},
          * if the class is {@code MethodHandle} and the name string is
          * {@code invokeExact} or {@code invoke}, the resulting
@@ -770,10 +861,10 @@
          * the constructor of the specified type.
          * The parameter types of the method handle will be those of the constructor,
          * while the return type will be a reference to the constructor's class.
-         * The constructor and all its argument types must be accessible to the lookup class.
+         * The constructor and all its argument types must be accessible to the lookup object.
          * <p>
-         * <em>(Note:  The requested type must have a return type of {@code void}.
-         * This is consistent with the JVM's treatment of constructor type descriptors.)</em>
+         * The requested type must have a return type of {@code void}.
+         * (This is consistent with the JVM's treatment of constructor type descriptors.)
          * <p>
          * The returned method handle will have
          * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
@@ -817,27 +908,26 @@
         }
 
         /**
-         * Produces an early-bound method handle for a virtual method,
-         * as if called from an {@code invokespecial}
-         * instruction from {@code caller}.
+         * Produces an early-bound method handle for a virtual method.
+         * It will bypass checks for overriding methods on the receiver,
+         * <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
+         * instruction from within the explicitly specified {@code specialCaller}.
          * The type of the method handle will be that of the method,
-         * with a suitably restricted receiver type (such as {@code caller}) prepended.
+         * with a suitably restricted receiver type prepended.
+         * (The receiver type will be {@code specialCaller} or a subtype.)
          * The method and all its argument types must be accessible
-         * to the caller.
+         * to the lookup object.
          * <p>
-         * When called, the handle will treat the first argument as a receiver,
-         * but will not dispatch on the receiver's type.
-         * (This direct invocation action is identical with that performed by an
-         * {@code invokespecial} instruction.)
-         * <p>
-         * If the explicitly specified caller class is not identical with the
-         * lookup class, or if this lookup object does not have private access
+         * Before method resolution,
+         * if the explicitly specified caller class is not identical with the
+         * lookup class, or if this lookup object does not have
+         * <a href="MethodHandles.Lookup.html#privacc">private access</a>
          * privileges, the access fails.
          * <p>
          * The returned method handle will have
          * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
          * the method's variable arity modifier bit ({@code 0x0080}) is set.
-         * <p>
+         * <p style="font-size:smaller;">
          * <em>(Note:  JVM internal methods named {@code "<init>"} are not visible to this API,
          * even though the {@code invokespecial} instruction can refer to them
          * in special circumstances.  Use {@link #findConstructor findConstructor}
@@ -993,7 +1083,7 @@
          * Produces an early-bound method handle for a non-static method.
          * The receiver must have a supertype {@code defc} in which a method
          * of the given name and type is accessible to the lookup class.
-         * The method and all its argument types must be accessible to the lookup class.
+         * The method and all its argument types must be accessible to the lookup object.
          * The type of the method handle will be that of the method,
          * without any insertion of an additional receiver parameter.
          * The given receiver will be bound into the method handle,
@@ -1008,17 +1098,17 @@
          * the given receiver value will be bound to it.)
          * <p>
          * This is equivalent to the following code:
-         * <blockquote><pre>
+         * <blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
-MethodHandle mh0 = lookup().{@link #findVirtual findVirtual}(defc, name, type);
-MethodHandle mh1 = mh0.{@link MethodHandle#bindTo bindTo}(receiver);
+MethodHandle mh0 = lookup().findVirtual(defc, name, type);
+MethodHandle mh1 = mh0.bindTo(receiver);
 MethodType mt1 = mh1.type();
 if (mh0.isVarargsCollector())
   mh1 = mh1.asVarargsCollector(mt1.parameterType(mt1.parameterCount()-1));
 return mh1;
-         * </pre></blockquote>
+         * }</pre></blockquote>
          * where {@code defc} is either {@code receiver.getClass()} or a super
          * type of that class, in which the requested method is accessible
          * to the lookup class.
@@ -1034,6 +1124,8 @@
          * @exception SecurityException if a security manager is present and it
          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
          * @throws NullPointerException if any argument is null
+         * @see MethodHandle#bindTo
+         * @see #findVirtual
          */
         public MethodHandle bind(Object receiver, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException {
             Class<? extends Object> refc = receiver.getClass(); // may get NPE
@@ -1043,7 +1135,8 @@
         }
 
         /**
-         * Makes a direct method handle to <i>m</i>, if the lookup class has permission.
+         * Makes a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
+         * to <i>m</i>, if the lookup class has permission.
          * If <i>m</i> is non-static, the receiver argument is treated as an initial argument.
          * If <i>m</i> is virtual, overriding is respected on every call.
          * Unlike the Core Reflection API, exceptions are <em>not</em> wrapped.
@@ -1090,13 +1183,21 @@
         /**
          * Produces a method handle for a reflected method.
          * It will bypass checks for overriding methods on the receiver,
-         * as if by a {@code invokespecial} instruction from within the {@code specialCaller}.
+         * <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
+         * instruction from within the explicitly specified {@code specialCaller}.
          * The type of the method handle will be that of the method,
-         * with the special caller type prepended (and <em>not</em> the receiver of the method).
+         * with a suitably restricted receiver type prepended.
+         * (The receiver type will be {@code specialCaller} or a subtype.)
          * If the method's {@code accessible} flag is not set,
          * access checking is performed immediately on behalf of the lookup class,
          * as if {@code invokespecial} instruction were being linked.
          * <p>
+         * Before method resolution,
+         * if the explicitly specified caller class is not identical with the
+         * lookup class, or if this lookup object does not have
+         * <a href="MethodHandles.Lookup.html#privacc">private access</a>
+         * privileges, the access fails.
+         * <p>
          * The returned method handle will have
          * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
          * the method's variable arity modifier bit ({@code 0x0080}) is set.
@@ -1141,8 +1242,7 @@
          *                                is set and {@code asVarargsCollector} fails
          * @throws NullPointerException if the argument is null
          */
-        @SuppressWarnings("rawtypes")  // Will be Constructor<?> after JSR 292 MR
-        public MethodHandle unreflectConstructor(Constructor c) throws IllegalAccessException {
+        public MethodHandle unreflectConstructor(Constructor<?> c) throws IllegalAccessException {
             MemberName ctor = new MemberName(c);
             assert(ctor.isConstructor());
             Lookup lookup = c.isAccessible() ? IMPL_LOOKUP : this;
@@ -1202,7 +1302,8 @@
         }
 
         /**
-         * Cracks a direct method handle created by this lookup object or a similar one.
+         * Cracks a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
+         * created by this lookup object or a similar one.
          * Security and access checks are performed to ensure that this lookup object
          * is capable of reproducing the target method handle.
          * This means that the cracking may fail if target is a direct method handle
@@ -1215,6 +1316,7 @@
          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
          * @throws IllegalArgumentException if the target is not a direct method handle or if access checking fails
          * @exception NullPointerException if the target is {@code null}
+         * @see MethodHandleInfo
          * @since 1.8
          */
         public MethodHandleInfo revealDirect(MethodHandle target) {
@@ -1282,7 +1384,7 @@
                 throw new MemberName(refc).makeAccessException("symbolic reference class is not public", this);
         }
 
-        /** Check name for an illegal leading "<" character. */
+        /** Check name for an illegal leading "&lt;" character. */
         void checkMethodName(byte refKind, String name) throws NoSuchMethodException {
             if (name.startsWith("<") && refKind != REF_newInvokeSpecial)
                 throw new NoSuchMethodException("illegal method name: "+name);
@@ -1730,13 +1832,12 @@
      * an {@link IllegalArgumentException} instead of invoking the target.
      * <p>
      * This method is equivalent to the following code (though it may be more efficient):
-     * <p><blockquote><pre>
+     * <blockquote><pre>{@code
 MethodHandle invoker = MethodHandles.invoker(type);
 int spreadArgCount = type.parameterCount() - leadingArgCount;
 invoker = invoker.asSpreader(Object[].class, spreadArgCount);
 return invoker;
-     * </pre></blockquote>
-     * <p>
+     * }</pre></blockquote>
      * This method throws no reflective or security exceptions.
      * @param type the desired target type
      * @param leadingArgCount number of fixed arguments, to be passed unchanged to the target
@@ -1762,9 +1863,7 @@
      * an additional leading argument of type {@code MethodHandle}.
      * <p>
      * This method is equivalent to the following code (though it may be more efficient):
-     * <p><blockquote><pre>
-publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)
-     * </pre></blockquote>
+     * {@code publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)}
      *
      * <p style="font-size:smaller;">
      * <em>Discussion:</em>
@@ -1779,7 +1878,7 @@
      * If spreading, collecting, or other argument transformations are required,
      * they can be applied once to the invoker {@code X} and reused on many {@code M}
      * method handle values, as long as they are compatible with the type of {@code X}.
-     * <p>
+     * <p style="font-size:smaller;">
      * <em>(Note:  The invoker method is not available via the Core Reflection API.
      * An attempt to call {@linkplain java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}
      * on the declared {@code invokeExact} or {@code invoke} method will raise an
@@ -1810,15 +1909,19 @@
      * If the target is a {@linkplain MethodHandle#asVarargsCollector variable arity method handle},
      * the required arity conversion will be made, again as if by {@link MethodHandle#asType asType}.
      * <p>
-     * A {@linkplain MethodType#genericMethodType general method type},
+     * This method is equivalent to the following code (though it may be more efficient):
+     * {@code publicLookup().findVirtual(MethodHandle.class, "invoke", type)}
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
+     * A {@linkplain MethodType#genericMethodType general method type} is one which
      * mentions only {@code Object} arguments and return values.
      * An invoker for such a type is capable of calling any method handle
      * of the same arity as the general type.
-     * <p>
-     * This method is equivalent to the following code (though it may be more efficient):
-     * <p><blockquote><pre>
-publicLookup().findVirtual(MethodHandle.class, "invoke", type)
-     * </pre></blockquote>
+     * <p style="font-size:smaller;">
+     * <em>(Note:  The invoker method is not available via the Core Reflection API.
+     * An attempt to call {@linkplain java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}
+     * on the declared {@code invokeExact} or {@code invoke} method will raise an
+     * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}.)</em>
      * <p>
      * This method throws no reflective or security exceptions.
      * @param type the desired target type
@@ -2105,7 +2208,7 @@
      * they will come after.
      * <p>
      * <b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2116,11 +2219,11 @@
 MethodHandle d0 = dropArguments(cat, 0, bigType.parameterList().subList(0,2));
 assertEquals(bigType, d0.type());
 assertEquals("yz", (String) d0.invokeExact(123, "x", "y", "z"));
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * This method is also equivalent to the following code:
      * <p><blockquote><pre>
-     * {@link #dropArguments(MethodHandle,int,Class...) dropArguments}(target, pos, valueTypes.toArray(new Class[0]))
+     * {@link #dropArguments(MethodHandle,int,Class...) dropArguments}{@code (target, pos, valueTypes.toArray(new Class[0]))}
      * </pre></blockquote>
      * @param target the method handle to invoke after the arguments are dropped
      * @param valueTypes the type(s) of the argument(s) to drop
@@ -2163,7 +2266,7 @@
      * they will come after.
      * <p>
      * <b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2178,11 +2281,11 @@
 assertEquals("xy", (String) d2.invokeExact("x", "y", "z"));
 MethodHandle d12 = dropArguments(cat, 1, int.class, boolean.class);
 assertEquals("xz", (String) d12.invokeExact("x", 12, true, "z"));
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * This method is also equivalent to the following code:
      * <p><blockquote><pre>
-     * {@link #dropArguments(MethodHandle,int,List) dropArguments}(target, pos, Arrays.asList(valueTypes))
+     * {@link #dropArguments(MethodHandle,int,List) dropArguments}{@code (target, pos, Arrays.asList(valueTypes))}
      * </pre></blockquote>
      * @param target the method handle to invoke after the arguments are dropped
      * @param valueTypes the type(s) of the argument(s) to drop
@@ -2228,8 +2331,8 @@
      * It is an error if there are elements of {@code filters}
      * (null or not)
      * which do not correspond to argument positions in the target.
-     * <b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><b>Example:</b>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2244,15 +2347,15 @@
 assertEquals("xY", (String) f1.invokeExact("x", "y")); // xY
 MethodHandle f2 = filterArguments(cat, 0, upcase, upcase);
 assertEquals("XY", (String) f2.invokeExact("x", "y")); // XY
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * V target(P... p, A[i]... a[i], B... b);
      * A[i] filter[i](V[i]);
      * T adapter(P... p, V[i]... v[i], B... b) {
      *   return target(p..., f[i](v[i])..., b...);
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      *
      * @param target the method handle to invoke after arguments are filtered
      * @param pos the position of the first argument to filter
@@ -2322,7 +2425,7 @@
      * In all cases, {@code pos} must be greater than or equal to zero, and
      * {@code pos} must also be less than or equal to the target's arity.
      * <p><b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2347,9 +2450,9 @@
 MethodHandle ts3_ts2_ts3 = collectArguments(ts3_ts2, 1, ts3);
 assertEquals("[top, [[up, down, strange], charm], bottom]",
              (String) ts3_ts2_ts3.invokeExact("top", "up", "down", "strange", "charm", "bottom"));
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * T target(A...,V,C...);
      * V filter(B...);
      * T adapter(A... a,B... b,C... c) {
@@ -2370,7 +2473,7 @@
      *   filter3(b...);
      *   return target3(a...,c...);
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * A collection adapter {@code collectArguments(mh, 0, coll)} is equivalent to
      * one which first "folds" the affected arguments, and then drops them, in separate
@@ -2426,8 +2529,8 @@
      * in the resulting adapted method handle.
      * The argument type of the filter (if any) must be identical to the
      * return type of the target.
-     * <b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><b>Example:</b>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2438,9 +2541,9 @@
 System.out.println((String) cat.invokeExact("x", "y")); // xy
 MethodHandle f0 = filterReturnValue(cat, length);
 System.out.println((int) f0.invokeExact("x", "y")); // 2
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * V target(A...);
      * T filter(V);
      * T adapter(A... a) {
@@ -2461,7 +2564,7 @@
      *   V v = target3(a...);
      *   filter3(v);
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * @param target the method handle to invoke before filtering the return value
      * @param filter method handle to call on the return value
      * @return method handle which incorporates the specified return value filtering logic
@@ -2517,8 +2620,8 @@
      * consider using {@link MethodHandle#asCollector asCollector} instead, since those
      * arguments will not need to be live on the stack on entry to the
      * target.)
-     * <b>Example:</b>
-     * <p><blockquote><pre>
+     * <p><b>Example:</b>
+     * <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
@@ -2531,9 +2634,9 @@
 MethodHandle catTrace = foldArguments(cat, trace);
 // also prints "boo":
 assertEquals("boojum", (String) catTrace.invokeExact("boo", "jum"));
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * // there are N arguments in A...
      * T target(V, A[N]..., B...);
      * V combiner(A...);
@@ -2548,7 +2651,7 @@
      *   combiner2(a...);
      *   return target2(a..., b...);
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * @param target the method handle to invoke after arguments are combined
      * @param combiner method handle to call initially on the incoming arguments
      * @return method handle which incorporates the specified argument folding logic
@@ -2591,7 +2694,7 @@
      * of the test must be boolean, and the test is allowed
      * to have fewer arguments than the other two method handles.
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * boolean test(A...);
      * T target(A...,B...);
      * T fallback(A...,B...);
@@ -2601,7 +2704,7 @@
      *   else
      *     return fallback(a..., b...);
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * Note that the test arguments ({@code a...} in the pseudocode) cannot
      * be modified by execution of the test, and so are passed unchanged
      * from the caller to the target or fallback as appropriate.
@@ -2653,7 +2756,7 @@
      * (similarly to the predicate in {@link #guardWithTest guardWithTest}).
      * Also, the handler must have an extra leading parameter of {@code exType} or a supertype.
      * <p> Here is pseudocode for the resulting adapter:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
      * T target(A..., B...);
      * T handler(ExType, A...);
      * T adapter(A... a, B... b) {
@@ -2663,7 +2766,7 @@
      *     return handler(ex, a...);
      *   }
      * }
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * Note that the saved arguments ({@code a...} in the pseudocode) cannot
      * be modified by execution of the target, and so are passed unchanged
      * from the caller to the handler, if the handler is invoked.
--- a/jdk/src/share/classes/java/lang/invoke/MethodType.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodType.java	Sat Oct 05 05:30:40 2013 -0700
@@ -77,7 +77,8 @@
  * A method type may be loaded by an {@code ldc} instruction which refers
  * to a suitable {@code CONSTANT_MethodType} constant pool entry.
  * The entry refers to a {@code CONSTANT_Utf8} spelling for the descriptor string.
- * For more details, see the <a href="package-summary.html#mtcon">package summary</a>.
+ * (For full details on method type constants,
+ * see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine Specification.)
  * <p>
  * When the JVM materializes a {@code MethodType} from a descriptor string,
  * all classes named in the descriptor must be accessible, and will be loaded.
@@ -940,10 +941,10 @@
      * Instead, the return type and parameter type arrays are written directly
      * from the {@code writeObject} method, using two calls to {@code s.writeObject}
      * as follows:
-     * <blockquote><pre>
+     * <blockquote><pre>{@code
 s.writeObject(this.returnType());
 s.writeObject(this.parameterArray());
-     * </pre></blockquote>
+     * }</pre></blockquote>
      * <p>
      * The deserialized field values are checked as if they were
      * provided to the factory method {@link #methodType(Class,Class[]) methodType}.
--- a/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java	Sat Oct 05 05:30:40 2013 -0700
@@ -38,7 +38,7 @@
  * Here is an example of a mutable call site which introduces a
  * state variable into a method handle chain.
  * <!-- JavaDocExamplesTest.testMutableCallSite -->
- * <blockquote><pre>
+ * <blockquote><pre>{@code
 MutableCallSite name = new MutableCallSite(MethodType.methodType(String.class));
 MethodHandle MH_name = name.dynamicInvoker();
 MethodType MT_str1 = MethodType.methodType(String.class);
@@ -50,10 +50,10 @@
 name.setTarget(MethodHandles.constant(String.class, "Fred"));
 assertEquals("FRED", (String) worker1.invokeExact());
 // (mutation can be continued indefinitely)
- * </pre></blockquote>
+ * }</pre></blockquote>
  * <p>
  * The same call site may be used in several places at once.
- * <blockquote><pre>
+ * <blockquote><pre>{@code
 MethodType MT_str2 = MethodType.methodType(String.class, String.class);
 MethodHandle MH_cat = lookup().findVirtual(String.class,
   "concat", methodType(String.class, String.class));
@@ -63,7 +63,7 @@
 name.setTarget(MethodHandles.constant(String.class, "Wilma"));
 assertEquals("WILMA", (String) worker1.invokeExact());
 assertEquals("Wilma, dear?", (String) worker2.invokeExact());
- * </pre></blockquote>
+ * }</pre></blockquote>
  * <p>
  * <em>Non-synchronization of target values:</em>
  * A write to a mutable call site's target does not force other threads
--- a/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java	Sat Oct 05 05:30:40 2013 -0700
@@ -55,7 +55,7 @@
  * At that point {@code guardWithTest} may ignore {@code T} and return {@code F}.
  * <p>
  * Here is an example of a switch point in action:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
 MethodHandle MH_strcat = MethodHandles.lookup()
     .findVirtual(String.class, "concat", MethodType.methodType(String.class, String.class));
 SwitchPoint spt = new SwitchPoint();
@@ -68,7 +68,7 @@
 SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
 assert(spt.hasBeenInvalidated());
 assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
- * </pre></blockquote>
+ * }</pre></blockquote>
  * <p style="font-size:smaller;">
  * <em>Discussion:</em>
  * Switch points are useful without subclassing.  They may also be subclassed.
@@ -82,7 +82,7 @@
  * <em>Implementation Note:</em>
  * A switch point behaves as if implemented on top of {@link MutableCallSite},
  * approximately as follows:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
 public class SwitchPoint {
   private static final MethodHandle
     K_true  = MethodHandles.constant(boolean.class, true),
@@ -106,7 +106,7 @@
     MutableCallSite.syncAll(mcss.toArray(new MutableCallSite[0]));
   }
 }
- * </pre></blockquote>
+ * }</pre></blockquote>
  * @author Remi Forax, JSR 292 EG
  */
 public class SwitchPoint {
--- a/jdk/src/share/classes/sun/invoke/WrapperInstance.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/sun/invoke/WrapperInstance.java	Sat Oct 05 05:30:40 2013 -0700
@@ -30,7 +30,7 @@
 /**
  * Private API used inside of java.lang.invoke.MethodHandles.
  * Interface implemented by every object which is produced by
- * {@link java.lang.invoke.MethodHandles#asInstance MethodHandles.asInstance}.
+ * {@link java.lang.invoke.MethodHandleProxies#asInterfaceInstance MethodHandleProxies.asInterfaceInstance}.
  * The methods of this interface allow a caller to recover the parameters
  * to {@code asInstance}.
  * This allows applications to repeatedly convert between method handles
--- a/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java	Sat Oct 05 05:30:40 2013 -0700
@@ -172,7 +172,7 @@
      * Decide if the given method type, attributed to a member or symbolic
      * reference of a given reference class, is really visible to that class.
      * @param type the supposed type of a member or symbolic reference of refc
-     * @param refc
+     * @param refc the class attempting to make the reference
      */
     public static boolean isTypeVisible(Class<?> type, Class<?> refc) {
         if (type == refc)  return true;  // easy check
@@ -197,7 +197,7 @@
      * Decide if the given method type, attributed to a member or symbolic
      * reference of a given reference class, is really visible to that class.
      * @param type the supposed type of a member or symbolic reference of refc
-     * @param refc
+     * @param refc the class attempting to make the reference
      */
     public static boolean isTypeVisible(java.lang.invoke.MethodType type, Class<?> refc) {
         for (int n = -1, max = type.parameterCount(); n < max; n++) {
@@ -210,8 +210,8 @@
 
     /**
      * Test if two classes have the same class loader and package qualifier.
-     * @param class1
-     * @param class2
+     * @param class1 a class
+     * @param class2 another class
      * @return whether they are in the same package
      */
     public static boolean isSamePackage(Class<?> class1, Class<?> class2) {
@@ -244,8 +244,8 @@
     /**
      * Test if two classes are defined as part of the same package member (top-level class).
      * If this is true, they can share private access with each other.
-     * @param class1
-     * @param class2
+     * @param class1 a class
+     * @param class2 another class
      * @return whether they are identical or nested together
      */
     public static boolean isSamePackageMember(Class<?> class1, Class<?> class2) {
@@ -287,8 +287,8 @@
     /**
      * Is the class loader of parentClass identical to, or an ancestor of,
      * the class loader of childClass?
-     * @param parentClass
-     * @param childClass
+     * @param parentClass a class
+     * @param childClass another class, which may be a descendent of the first class
      * @return whether parentClass precedes or equals childClass in class loader order
      */
     public static boolean classLoaderIsAncestor(Class<?> parentClass, Class<?> childClass) {
--- a/jdk/src/share/classes/sun/invoke/util/VerifyType.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/src/share/classes/sun/invoke/util/VerifyType.java	Sat Oct 05 05:30:40 2013 -0700
@@ -41,8 +41,8 @@
      * True if a value can be stacked as the source type and unstacked as the
      * destination type, without violating the JVM's type consistency.
      *
-     * @param call the type of a stacked value
-     * @param recv the type by which we'd like to treat it
+     * @param src the type of a stacked value
+     * @param dst the type by which we'd like to treat it
      * @return whether the retyping can be done without motion or reformatting
      */
     public static boolean isNullConversion(Class<?> src, Class<?> dst) {
@@ -67,9 +67,8 @@
 
     /**
      * Specialization of isNullConversion to reference types.
-
-     * @param call the type of a stacked value
-     * @param recv the reference type by which we'd like to treat it
+     * @param src the type of a stacked value
+     * @param dst the reference type by which we'd like to treat it
      * @return whether the retyping can be done without a cast
      */
     public static boolean isNullReferenceConversion(Class<?> src, Class<?> dst) {
--- a/jdk/test/java/lang/invoke/AccessControlTest.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/test/java/lang/invoke/AccessControlTest.java	Sat Oct 05 05:30:40 2013 -0700
@@ -133,7 +133,7 @@
         }
 
         /** Simulate all assertions from the spec. for Lookup.in:
-         * <hr/>
+         * <hr>
          * Creates a lookup on the specified new lookup class.
          * [A1] The resulting object will report the specified
          * class as its own {@link #lookupClass lookupClass}.
@@ -155,7 +155,7 @@
          * </ul>
          * Other than the above cases, the new lookup will have the same
          * access capabilities as the original. [A8]
-         * <hr/>
+         * <hr>
          */
         public LookupCase in(Class<?> c2) {
             Class<?> c1 = lookupClass();
--- a/jdk/test/java/lang/invoke/MethodHandlesTest.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/test/java/lang/invoke/MethodHandlesTest.java	Sat Oct 05 05:30:40 2013 -0700
@@ -496,7 +496,7 @@
         return lookup.in(defc);
     }
 
-    /** Is findVirtual (etc.) of "<init>" supposed to elicit a NoSuchMethodException? */
+    /** Is findVirtual (etc.) of "&lt;init&lt;" supposed to elicit a NoSuchMethodException? */
     final static boolean INIT_REF_CAUSES_NSME = true;
 
     @Test
--- a/jdk/test/java/lang/invoke/RevealDirectTest.java	Sat Oct 05 05:30:39 2013 -0700
+++ b/jdk/test/java/lang/invoke/RevealDirectTest.java	Sat Oct 05 05:30:40 2013 -0700
@@ -104,6 +104,9 @@
         private static Lookup localLookup() { return lookup(); }
         private static List<Member> members() { return getMembers(lookup().lookupClass()); };
     }
+    static class Nestmate {
+        private static Lookup localLookup() { return lookup(); }
+    }
 
     static boolean VERBOSE = false;
 
@@ -152,7 +155,10 @@
                                   getMembers(Method.class, "invoke"));
         mems = callerSensitive(true, publicOnly(mems));
         // CS methods cannot be looked up with publicLookup
-        testOnMembersNoLookup("testCallerSensitiveNegative", mems, publicLookup());
+        testOnMembersNoLookup("testCallerSensitiveNegative/1", mems, publicLookup());
+        // CS methods have to be revealed with a matching lookupClass
+        testOnMembersNoReveal("testCallerSensitiveNegative/2", mems, Simple.localLookup(), publicLookup());
+        testOnMembersNoReveal("testCallerSensitiveNegative/3", mems, Simple.localLookup(), Nestmate.localLookup());
     }
     @Test public void testMethodHandleNatives() throws Throwable {
         if (VERBOSE)  System.out.println("@Test testMethodHandleNatives");
@@ -703,7 +709,7 @@
             try {
                 info = revLookup.revealDirect(mh);
                 if (expectEx2)  throw new AssertionError("unexpected revelation for negative test");
-            } catch (Throwable ex2) {
+            } catch (IllegalArgumentException|SecurityException ex2) {
                 if (VERBOSE)  System.out.println("  "+variation+": "+res+" => "+mh.getClass().getName()+" => (EX2)"+ex2);
                 if (expectEx2)
                     continue;  // this is OK; we expected the reflect to fail