--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/LineLocationToProbeCollectionMap.java	Wed Aug 20 16:50:25 2014 +0200
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/LineLocationToProbeCollectionMap.java	Wed Aug 20 15:14:30 2014 -0700
@@ -34,6 +34,7 @@
  * a collection of {@link Probe}s whose associated {@link SourceSection} starts on that line.
  */
 public class LineLocationToProbeCollectionMap implements ProbeListener {
+
     /**
      * Map: Source line ==> probes associated with source sections starting on the line.
      */
@@ -69,7 +70,7 @@
     }
 
     /**
-     * Adds a probe to the given line.
+     * Records creation of a probe whose associated source starts on the given line.
      * <p>
      * If the line already exists in the internal {@link #lineToProbesMap}, this probe will be added
      * to the existing collection. If no line already exists in the internal map, then a new key is
@@ -97,11 +98,11 @@
     }
 
     /**
-     * Returns a collection of {@link Probe}s at the given {@link LineLocation}. If there are no
-     * probes at that line, an empty list is returned.
+     * Returns a collection of {@link Probe}s whose associated source begings at the given
+     * {@link LineLocation}. If there are no probes at that line, an empty list is returned.
      *
      * @param line The line to check.
-     * @return A iterable collection of probes at the given line.
+     * @return A collection of probes at the given line.
      */
     private Collection<Probe> getProbesAtLine(LineLocation line) {
         Collection<Probe> probeList = lineToProbesMap.get(line);

--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java	Wed Aug 20 16:50:25 2014 +0200
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java	Wed Aug 20 15:14:30 2014 -0700
@@ -43,10 +43,6 @@
     /**
      * Called when a {@link #tagTrap} is activated in a Probe.
      */
-    /**
-     * The callback to be triggered by the {@link #tagTrap}.
-     *
-     */
     private final ProbeCallback probeCallback;
 
     /**
@@ -72,9 +68,7 @@
     }
 
     /**
-     * Add a {@link ProbeListener} to receive events.
-     *
-     * @param listener The listener to be added.
+     * Adds a {@link ProbeListener} to receive events.
      */
     public void addProbeListener(ProbeListener listener) {
         assert listener != null;
@@ -82,9 +76,7 @@
     }
 
     /**
-     * Remove a {@link ProbeListener}. If no matching probe listener is found, nothing happens.
-     *
-     * @param removeListener
+     * Removes a {@link ProbeListener}. Ignored if listener not found.
      */
     public void removeProbeListener(ProbeListener removeListener) {
         final List<ProbeListener> listeners = new ArrayList<>(probeListeners);
@@ -97,10 +89,7 @@
 
     /**
      * Creates a new {@link Probe} associated with a {@link SourceSection} of code corresponding to
-     * a Trufle AST node.
-     *
-     * @param source The source section to associate with this probe.
-     * @return The probe that was created.
+     * a Truffle AST node.
      */
     public Probe createProbe(SourceSection source) {
         assert source != null;
@@ -119,7 +108,7 @@
      * Returns the subset of all {@link Probe}s holding a particular {@link SyntaxTag}, or the whole
      * collection if the specified tag is {@code null}.
      *
-     * @return An iterable collection of probes containing the given tag.
+     * @return A collection of probes containing the given tag.
      */
     public Collection<Probe> findProbesTaggedAs(SyntaxTag tag) {
         final List<Probe> probes = new ArrayList<>();
@@ -132,8 +121,10 @@
     }
 
     /**
-     * Calls {@link ProbeImpl#setTrap(SyntaxTagTrap)} for all probes with the given
-     * {@link SyntaxTag} . There can only be one tag trap set at a time.
+     * Sets the current "tag trap", which will cause a callback to be triggered whenever execution
+     * reaches a Probe (existing or subsequently created) with the specified tag. There can only be
+     * one tag trap set at a time.
+     * <p>
      *
      * @param tagTrap The {@link SyntaxTagTrap} to set.
      * @throws IllegalStateException if a trap is currently set.