# HG changeset patch # User Bernhard Urban # Date 1408449074 -7200 # Node ID 1051d6e4b61bc6ee701b55d6c4ee54c19056713a # Parent a8af2abc2039bafd2d2c5c56273a27536dbca0ec truffle api: update comments diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/CallTarget.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/CallTarget.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/CallTarget.java Tue Aug 19 13:51:14 2014 +0200 @@ -30,7 +30,7 @@ public interface CallTarget { /** - * Calls this target as a root method.. + * Calls this target as a root method. * * @param arguments passed arguments as an object array * @return the return result of the call diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTNodeProber.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTNodeProber.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTNodeProber.java Tue Aug 19 13:51:14 2014 +0200 @@ -27,11 +27,10 @@ import com.oracle.truffle.api.nodes.*; /** - * Implementation of a policy for instrumenting inserting a {@link Probe} at a Truffle AST - * node. + * Methods for inserting a {@link Probe} at a Truffle AST node. *

- * Note that this interface is guest language agnostic, but current extensions are - * language-specific. This will be revisited. + * This interface is guest language agnostic, but current extensions are language-specific. This + * will be revisited. *

* Disclaimer: experimental interface under development. Really! */ diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTPrinter.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTPrinter.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTPrinter.java Tue Aug 19 13:51:14 2014 +0200 @@ -29,7 +29,8 @@ import com.oracle.truffle.api.nodes.*; /** - * Language-agnostic access to AST-based debugging support. + * Access to AST-based debugging support, which is could be language implementation specific in the + * details chosen to be presented. *

* WARNING: this interface is under development and will change substantially. */ @@ -37,7 +38,7 @@ /** * Prints a textual AST display, one line per node, with nesting. - * + * * @param p * @param node the root node of the display. * @param maxDepth the maximum number of levels to print below the root @@ -47,7 +48,7 @@ /** * Creates a textual AST display, one line per node, with nesting. - * + * * @param node the root node of the display. * @param maxDepth the maximum number of levels to print below the root * @param markNode a node to mark with a textual arrow prefix, if present. @@ -56,7 +57,7 @@ /** * Creates a textual AST display, one line per node, with nesting. - * + * * @param node the root node of the display. * @param maxDepth the maximum number of levels to print below the root */ diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ExecutionEvents.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ExecutionEvents.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ExecutionEvents.java Tue Aug 19 13:51:14 2014 +0200 @@ -28,8 +28,9 @@ import com.oracle.truffle.api.nodes.*; /** - * Normal events during program execution at Truffle AST nodes that are reported via a {@link Probe} - * associated with the node, and made available to the probe's attached {@link Instrument}s. + * Normal events at each Truffle AST {@link Node} that occur during guest language execution, and + * which the {@link Probe} associated with that node, if any, reports to every {@link Instrument} + * attached to the {@link Probe}. *

* Disclaimer: experimental interface under development. */ diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SyntaxTagged.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SyntaxTagged.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SyntaxTagged.java Tue Aug 19 13:51:14 2014 +0200 @@ -36,12 +36,13 @@ public interface SyntaxTagged { /** - * Is this node tagged as belonging to a particular category of language constructs? + * Is this node tagged as belonging to a particular human-sensible category of language + * constructs? */ boolean isTaggedAs(SyntaxTag tag); /** - * In which categories has this node been tagged (empty set if none). + * In which user-sensible categories has this node been tagged (empty set if none). */ Iterable getSyntaxTags(); diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/InstrumentationNode.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/InstrumentationNode.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/InstrumentationNode.java Tue Aug 19 13:51:14 2014 +0200 @@ -359,10 +359,19 @@ this.next = null; } + /** + * Returns the {@link SourceSection} associated with this probe. + */ public SourceSection getSourceLocation() { return source; } + /** + * Tags this probe with the given {@link SyntaxTag}. If the tag already exists, the tag is + * not added. + * + * @param tag The tag to add to this probe. + */ @SlowPath public void tagAs(SyntaxTag tag) { assert tag != null; @@ -372,11 +381,22 @@ } } + /** + * Checks if this probe has been tagged with the given tag. + * + * @param tag The {@link SyntaxTag} to check for. + * @return True if this probe has the given tag, false otherwise. + */ public boolean isTaggedAs(SyntaxTag tag) { assert tag != null; return tags.contains(tag); } + /** + * Returns an iterable collection of all syntax tags on this probe. + * + * @return A collection of {@link SyntaxTag}s. + */ public Iterable getSyntaxTags() { return tags; } diff -r a8af2abc2039 -r 1051d6e4b61b graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java Tue Aug 19 09:58:41 2014 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java Tue Aug 19 13:51:14 2014 +0200 @@ -43,6 +43,10 @@ /** * Called when a {@link #tagTrap} is activated in a Probe. */ + /** + * The callback to be triggered by the {@link #tagTrap}. + * + */ private final ProbeCallback probeCallback; /** @@ -114,6 +118,8 @@ /** * 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. */ public Collection findProbesTaggedAs(SyntaxTag tag) { final List probes = new ArrayList<>();