# HG changeset patch
# User Michael Van De Vanter  <michael.van.de.vanter@oracle.com>
# Date 1390451332 28800
# Node ID 4d47e9c0df231c7fcfeefbbc41c68225881cd918
# Parent  fbf4489292600bd6693546481958fe213cb6168f
Truffle/Instrumentation:  Javadoc and cleanup

diff -r fbf448929260 -r 4d47e9c0df23 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/DebugManager.java
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/DebugManager.java	Sat Jan 18 22:12:42 2014 -0800
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/DebugManager.java	Wed Jan 22 20:28:52 2014 -0800
@@ -37,8 +37,29 @@
 public interface DebugManager {
 
     /**
-     * Receives notification of a suspended execution context; execution resumes when this method
-     * returns.
+     * Informs the {@link DebugManager} that the Guest Language runtime is starting to load a
+     * source. Care should be taken to ensure that under any circumstance there is always a
+     * following call to {@link #notifyFinishedLoading(Source)} with the same argument.
+     */
+    void notifyStartLoading(Source source);
+
+    /**
+     * Informs the {@link DebugManager} that the Guest Language runtime has finished loading a
+     * source. Care should be taken to ensure that under any circumstance there is always a prior
+     * call to {@link #notifyStartLoading(Source)} with the same argument.
+     */
+    void notifyFinishedLoading(Source source);
+
+    /**
+     * Return a reference to the (canonical) instrumentation site associated with a particular
+     * source code location; this site will have effect on any Truffle/AST implementation
+     * corresponding to the source location, even if the AST is copied multiple times.
+     */
+    ProbeChain getProbeChain(SourceSection sourceSection);
+
+    /**
+     * Informs the {@link DebugManager} that Truffle execution has halted; execution will resume
+     * when this method returns.
      * 
      * @param astNode a guest language AST node that represents the current execution site, assumed
      *            not to be any kind of {@link InstrumentationNode},
@@ -46,10 +67,4 @@
      */
     void haltedAt(Node astNode, MaterializedFrame frame);
 
-    void notifyFinishedLoading(Source source);
-
-    void notifyStartLoading(Source source);
-
-    ProbeChain getProbeChain(SourceSection sourceSection);
-
 }
diff -r fbf448929260 -r 4d47e9c0df23 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/DefaultDebugManager.java
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/DefaultDebugManager.java	Sat Jan 18 22:12:42 2014 -0800
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/DefaultDebugManager.java	Wed Jan 22 20:28:52 2014 -0800
@@ -32,7 +32,11 @@
 import com.oracle.truffle.api.nodes.instrument.InstrumentationProbeNode.ProbeChain;
 import com.oracle.truffle.api.source.*;
 
-public final class DefaultDebugManager implements DebugManager {
+/**
+ * A minimal, language-agnostic implementation that tracks loaded sources, and keeps maps describing
+ * what locations in the source have instrumentation available.
+ */
+public class DefaultDebugManager implements DebugManager {
 
     private final Set<Source> loadedSources = new HashSet<>();
 
@@ -87,13 +91,11 @@
         return probeChain;
     }
 
-    @Override
     public void notifyStartLoading(Source source) {
         assert beingLoaded == null;
         beingLoaded = source;
     }
 
-    @Override
     public void notifyFinishedLoading(Source source) {
         assert source == beingLoaded;
         loadedSources.add(source);