--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java	Mon Apr 13 11:05:58 2015 -0700
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java	Mon Apr 13 15:00:57 2015 -0700
@@ -30,8 +30,9 @@
 import com.oracle.truffle.api.nodes.*;
 import com.oracle.truffle.api.source.*;
 
-// TODO (mlvdv) move all this to a factory implemented in .impl (together with Probe),
-// then break out some of the nested classes into package privates.
+// TODO (mlvdv) these statics should not be global.  Move them to some kind of context.
+// TODO (mlvdv) migrate factory into .impl (together with Probe)? break out nested classes?
+
 /**
  * A <em>binding</em> between:
  * <ol>
@@ -41,8 +42,8 @@
  * </ol>
  * <p>
  * Client-oriented documentation for the use of Instruments is available online at <a
- * HREF="https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events">Listening for
- * Execution Events</a>
+ * HREF="https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events"
+ * >https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events</a>
  * <p>
  * The implementation of Instruments is complicated by the requirement that Truffle be able to clone
  * ASTs at any time. In particular, any instrumentation-supporting Nodes that have been attached to
@@ -62,29 +63,38 @@
  * <ul>
  * <li>A new Instrument is created in permanent association with a client-provided
  * <em>listener.</em></li>
+ *
  * <li>Multiple Instruments may share a single listener.</li>
+ *
  * <li>An Instrument does nothing until it is {@linkplain Probe#attach(Instrument) attached} to a
  * Probe, at which time the Instrument begins routing execution events from the Probe's AST location
  * to the Instrument's listener.</li>
+ *
  * <li>Neither Instruments nor Probes are {@link Node}s.</li>
+ *
  * <li>A Probe has a single source-based location in an AST, but manages a separate
  * <em>instrumentation chain</em> of Nodes at the equivalent location in each clone of the AST.</li>
  * <li>When a probed AST is cloned, the instrumentation chain associated with each Probe is cloned
  * along with the rest of the AST.</li>
+ *
  * <li>When a new Instrument (for example an instance of {@link SimpleInstrument} is attached to a
  * Probe, the Instrument inserts a new instance of its private Node type,
  * {@link SimpleInstrument.SimpleInstrumentNode}, into <em>each of the instrument chains</em>
  * managed by the Probe, i.e. one node instance per existing clone of the AST.</li>
+ *
  * <li>If an Instrument is attached to a Probe in an AST that subsequently gets cloned, then the
  * Instrument's private Node type will be cloned along with the rest of the the AST.</li>
  * <li>Each Instrument's private Node type is a dynamic inner class whose only state is in the
  * shared (outer) Instrument instance; that state includes a reference to the Instrument's listener.
  * </li>
+ *
  * <li>When an Instrument that has been attached to a Probe is {@linkplain #dispose() disposed}, the
  * Instrument searches every instrument chain associated with the Probe and removes the instance of
  * its private Node type.</li>
+ *
  * <li>Attaching and disposing an Instrument at a Probe <em>deoptimizes</em> any compilations of the
  * AST.</li>
+ *
  * </ul>
  *
  * @see Probe

--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java	Mon Apr 13 11:05:58 2015 -0700
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java	Mon Apr 13 15:00:57 2015 -0700
@@ -34,38 +34,62 @@
 import com.oracle.truffle.api.source.*;
 import com.oracle.truffle.api.utilities.*;
 
-//TODO (mlvdv) migrate some of this to external documentation.
+//TODO (mlvdv) these statics should not be global.  Move them to some kind of context.
+
 /**
- * A binding between a particular <em>location</em> in the Truffle AST representation of a running
- * Guest Language (GL) program (i.e. a {@link Node}) and a dynamically managed collection of
- * "attached" {@linkplain Instrument instrumentation} for use by external tools. The instrumentation
- * is intended to persist at the location, even if the specific node instance is
- * {@linkplain Node#replace(Node) replaced}.
+ * A <em>binding</em> between:
+ * <ol>
+ * <li>A program location in an executing Truffle AST (defined by a {@link SourceSection}), and</li>
+ * <li>A dynamically managed collection of "attached" {@linkplain Instrument Instruments} that
+ * receive event notifications on behalf of external clients.</li>
+ * </ol>
  * <p>
- * The effect of a binding is to intercept {@linkplain TruffleEvents execution events} arriving at
- * the node and notify each attached {@link Instrument} before execution is allowed to proceed to
- * the child.
+ * Client-oriented documentation for the use of Probes is available online at <a
+ * HREF="https://wiki.openjdk.java.net/display/Graal/Finding+Probes"
+ * >https://wiki.openjdk.java.net/display/Graal/Finding+Probes</a>
  * <p>
- * A Probe is "inserted" into a GL node via a call to {@link Node#probe()}. No more than one Probe
- * can be inserted at a node.
+ * <h4>Implementation notes:</h4>
  * <p>
- * The "probing" of a Truffle AST must be done after it is complete (i.e. with parent pointers
- * correctly assigned), but before any executions. This is done by creating an instance of
- * {@link ASTProber} and registering it via {@link #registerASTProber(ASTProber)}, after which it
- * will be automatically applied to newly created ASTs.
- * <p>
- * Each Probe may also have assigned to it any number of {@link SyntaxTag}s, for example identifying
- * a node as a {@linkplain StandardSyntaxTag#STATEMENT STATEMENT}. Tags can be queried by tools to
- * configure behavior relevant to each probed node.
- * <p>
- * Instrumentation is implemented by modifying ASTs, both by inserting nodes into each AST at probed
- * locations and by attaching additional nodes that implement dynamically attached instruments.
- * Attached instrumentation code become, in effect, part of the GL program, and is subject to the
- * same levels of optimization as other GL code. This implementation accounts properly for the fact
- * that Truffle frequently <em>clones</em> ASTs, along with any attached instrumentation nodes. A
- * {@link Probe}, along with attached {@link Instrument}s, represents a <em>logical</em> binding
- * with a source code location, producing event notifications that are (mostly) independent of which
- * AST clone is executing.
+ * <ul>
+ * <li>A Probe must be permanently associated with a <em>program location</em>, defined by a
+ * particular {@link SourceSection}, even though:
+ * <ul>
+ * <li>that location is represented in an AST as a {@link Node}, which might be replaced through
+ * optimizations such as specialization, and</li>
+ * <li>Truffle may <em>clone</em> the AST so that the location is actually represented by multiple
+ * Nodes in multiple ASTs.</li>
+ * </ul>
+ * </li>
+ *
+ * <li>The effect of the binding is to intercept {@linkplain TruffleEvents execution events}
+ * arriving at the "probed" AST node and notify each attached {@link Instrument} before execution is
+ * allowed to proceed to the child and again after execution completes.</li>
+ *
+ * <li>A Probe is "inserted" into a GL node via a call to {@link Node#probe()}. No more than one
+ * Probe can be inserted at a node; a redundant call returns the existing Probe<./li>
+ *
+ * <li>The "probing" of a Truffle AST must be done after the AST is complete (i.e. parent pointers
+ * correctly assigned), but before any cloning or executions. This is done by creating an instance
+ * of {@link ASTProber} and registering it via {@link #registerASTProber(ASTProber)}, after which it
+ * will be applied automatically to every newly created AST.</li>
+ *
+ * <li>An AST node becomes <em>probed</em> by insertion of a {@link ProbeNode.WrapperNode} into the
+ * AST, together with an associated {@link ProbeNode} that routes events to all the
+ * {@linkplain Instrument Instruments} attached to its <em>instrument chain</em>.</li>
+ *
+ * <li>When Truffle clones an AST, any attached WrapperNodes and ProbeNodes are cloned as well,
+ * together with their attached instrument chains. The {@link Probe} instance intercepts cloning
+ * events and keeps track of all copies.</li>
+ *
+ * <li>All attached {@link InstrumentationNode}s effectively become part of the running program:
+ * <ul>
+ * <li>Good News: instrumentation code implicitly benefits from every kind of Truffle optimization.</li>
+ * <li>Bad News: instrumentation code must be implemented carefully to avoid interfering with any
+ * Truffle optimizations.</li>
+ * </ul>
+ * </li>
+ *
+ * </ul>
  *
  * @see Instrument
  * @see ASTProber
@@ -173,6 +197,7 @@
         return taggedProbes;
     }
 
+    // TODO (mlvdv) can this be generalized to permit multiple traps without a performance hit?
     /**
      * Sets the current "tag trap"; there can be no more than one set at a time.
      * <ul>

--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceTag.java	Mon Apr 13 11:05:58 2015 -0700
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceTag.java	Mon Apr 13 15:00:57 2015 -0700
@@ -27,8 +27,8 @@
 /**
  * Categorical information (best implemented as enums} about particular sources of Guest Language
  * code that can be useful to configure behavior of both the language runtime and external tools.
- * These might include {@linkplain Source.Tags standard tags} noting, for example,
- * whether the source was read from a file and whether it should be considered library code.
+ * These might include {@linkplain Source.Tags standard tags} noting, for example, whether the
+ * source was read from a file and whether it should be considered library code.
  * <p>
  * The need for additional tags is likely to arise, in some cases because of issue specific to a
  * Guest Language, but also for help configuring the behavior of particular tools.