--- a/jdk/src/share/classes/java/dyn/CallSite.java	Mon May 11 12:08:15 2009 -0700
+++ b/jdk/src/share/classes/java/dyn/CallSite.java	Mon May 11 21:09:58 2009 -0700
@@ -28,18 +28,28 @@
 import sun.dyn.util.BytecodeName;
 
 /**
- * An <code>invokedynamic</code> call site, as reified to the bootstrap method.
- * Every instance of a call site corresponds to a distinct instance
- * of the <code>invokedynamic</code> instruction.
- * Call sites have state, one reference word, called the <code>target</code>,
- * and typed as a {@link MethodHandle}.  When this state is null (as it is
- * initially) the call site is in the unlinked state.  Otherwise, it is said
- * to be linked to its target.
+ * An {@code invokedynamic} call site, as reified by the
+ * containing class's bootstrap method.
+ * Every call site object corresponds to a distinct instance
+ * of the <code>invokedynamic</code> instruction, and vice versa.
+ * Every call site has one state variable, called the {@code target}.
+ * It is typed as a {@link MethodHandle}.  This state is never null, and
+ * it is the responsibility of the bootstrap method to produce call sites
+ * which have been pre-linked to an initial target method.
  * <p>
- * When an unlinked call site is executed, a bootstrap routine is called
- * to finish the execution of the call site, and optionally to link
- * the call site.
+ * (Note:  The bootstrap method may elect to produce call sites of a
+ * language-specific subclass of {@code CallSite}.  In such a case,
+ * the subclass may claim responsibility for initializing its target to
+ * a non-null value, by overriding {@link #initialTarget}.)
  * <p>
+ * An {@code invokedynamic} instruction which has not yet been executed
+ * is said to be <em>unlinked</em>.  When an unlinked call site is executed,
+ * the containing class's bootstrap method is called to manufacture a call site,
+ * for the instruction.  If the bootstrap method does not assign a non-null
+ * value to the new call site's target variable, the method {@link #initialTarget}
+ * is called to produce the new call site's first target method.
+ * <p>
+ * @see Linkage#registerBootstrapMethod(java.lang.Class, java.dyn.MethodHandle)
  * @author John Rose, JSR 292 EG
  */
 public class CallSite {
@@ -52,6 +62,15 @@
     final String name;
     final MethodType type;
 
+    /**
+     * Make a call site given the parameters from a call to the bootstrap method.
+     * The resulting call site is in an unlinked state, which means that before
+     * it is returned from a bootstrap method call it must be provided with
+     * a target method via a call to {@link CallSite#setTarget}.
+     * @param caller the class in which the relevant {@code invokedynamic} instruction occurs
+     * @param name the name specified by the {@code invokedynamic} instruction
+     * @param type the method handle type derived from descriptor of the {@code invokedynamic} instruction
+     */
     public CallSite(Object caller, String name, MethodType type) {
         this.caller = caller;
         this.name = name;
@@ -73,7 +92,9 @@
      * <p>
      * If the bootstrap method itself does not initialize the call site,
      * this method must be overridden, because it just raises an
-     * {@code InvokeDynamicBootstrapError}.
+     * {@code InvokeDynamicBootstrapError}, which in turn causes the
+     * linkage of the {@code invokedynamic} instruction to terminate
+     * abnormally.
      */
     protected MethodHandle initialTarget() {
         throw new InvokeDynamicBootstrapError("target must be initialized before call site is linked: "+this);
@@ -81,7 +102,7 @@
 
     /**
      * Report the current linkage state of the call site.  (This is mutable.)
-     * The value is null if and only if the call site is currently unlinked.
+     * The value maybe null only if the call site is currently unlinked.
      * When a linked call site is invoked, the target method is used directly.
      * When an unlinked call site is invoked, its bootstrap method receives
      * the call, as if via {@link Linkage#bootstrapInvokeDynamic}.
@@ -113,8 +134,9 @@
      * into the bootstrap method and/or the target methods used
      * at any given call site.
      * @param target the new target, or null if it is to be unlinked
-     * @throws WrongMethodTypeException if the new target is not null
-     *         and has a method type that differs from the call site's {@link #type}
+     * @throws NullPointerException if the proposed new target is null
+     * @throws WrongMethodTypeException if the proposed new target
+     *         has a method type that differs from the call site's {@link #type()}
      */
     public void setTarget(MethodHandle target) {
         checkTarget(target);
@@ -122,6 +144,7 @@
     }
 
     protected void checkTarget(MethodHandle target) {
+        target.type();  // provoke NPE
         if (!canSetTarget(target))
             throw new WrongMethodTypeException(String.valueOf(target));
     }
@@ -132,7 +155,7 @@
 
     /**
      * Report the class containing the call site.
-     * This is immutable static context.
+     * This is an immutable property of the call site, set from the first argument to the constructor.
      * @return class containing the call site
      */
     public Class<?> callerClass() {
@@ -141,7 +164,7 @@
 
     /**
      * Report the method name specified in the {@code invokedynamic} instruction.
-     * This is immutable static context.
+     * This is an immutable property of the call site, set from the second argument to the constructor.
      * <p>
      * Note that the name is a JVM bytecode name, and as such can be any
      * non-empty string, as long as it does not contain certain "dangerous"
@@ -187,7 +210,7 @@
      * which are derived from its bytecode-level invocation descriptor.
      * The types are packaged into a {@link MethodType}.
      * Any linked target of this call site must be exactly this method type.
-     * This is immutable static context.
+     * This is an immutable property of the call site, set from the third argument to the constructor.
      * @return method type specified by the call site
      */
     public MethodType type() {