--- a/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java	Fri Mar 11 17:07:57 2016 -0800
+++ b/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java	Sun Mar 13 20:26:29 2016 +0100
@@ -99,13 +99,16 @@
      * <p>
      * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}
      * of this lookup object will be {@link java.lang.Object}.
+     * Consequently, the lookup context of this lookup object will be the bootstrap
+     * class loader, which means it cannot find user classes.
      *
      * <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
      * {@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.
+     * such a change would confer no new access rights,
+     * but may change the lookup context by virtue of changing the class loader.
      * A public lookup object is always subject to
      * <a href="MethodHandles.Lookup.html#secmgr">security manager checks</a>.
      * Also, it cannot access
@@ -641,6 +644,11 @@
          * then no members, not even public members, will be accessible.
          * (In all other cases, public members will continue to be accessible.)
          * </ul>
+         * <p>
+         * The resulting lookup's capabilities for loading classes
+         * (used during {@link #findClass} invocations)
+         * are determined by the lookup class' loader,
+         * which may change due to this operation.
          *
          * @param requestedLookupClass the desired lookup class for the new lookup object
          * @return a lookup object which reports the desired lookup class
@@ -939,13 +947,17 @@
         /**
          * Looks up a class by name from the lookup context defined by this {@code Lookup} object. The static
          * initializer of the class is not run.
+         * <p>
+         * The lookup context here is determined by the {@linkplain #lookupClass() lookup class}, its class
+         * loader, and the {@linkplain #lookupModes() lookup modes}. In particular, the method first attempts to
+         * load the requested class, and then determines whether the class is accessible to this lookup object.
          *
          * @param targetName the fully qualified name of the class to be looked up.
          * @return the requested class.
          * @exception SecurityException if a security manager is present and it
          *            <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
          * @throws LinkageError if the linkage fails
-         * @throws ClassNotFoundException if the class does not exist.
+         * @throws ClassNotFoundException if the class cannot be loaded by the lookup class' loader.
          * @throws IllegalAccessException if the class is not accessible, using the allowed access
          * modes.
          * @exception SecurityException if a security manager is present and it
@@ -960,6 +972,9 @@
         /**
          * Determines if a class can be accessed from the lookup context defined by this {@code Lookup} object. The
          * static initializer of the class is not run.
+         * <p>
+         * The lookup context here is determined by the {@linkplain #lookupClass() lookup class} and the
+         * {@linkplain #lookupModes() lookup modes}.
          *
          * @param targetClass the class to be access-checked
          *