Mercurial > hg > truffle
changeset 16859:1051d6e4b61b
truffle api: update comments
| author | Bernhard Urban <bernhard.urban@jku.at> |
|---|---|
| date | Tue, 19 Aug 2014 13:51:14 +0200 |
| parents | a8af2abc2039 |
| children | 2270852ee1ef |
| files | graal/com.oracle.truffle.api/src/com/oracle/truffle/api/CallTarget.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTNodeProber.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTPrinter.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ExecutionEvents.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SyntaxTagged.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/InstrumentationNode.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/ProbeManager.java |
| diffstat | 7 files changed, 41 insertions(+), 13 deletions(-) [+] |
line wrap: on
line diff
--- 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
--- 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 <em>instrumenting</em> inserting a {@link Probe} at a Truffle AST - * node. + * Methods for inserting a {@link Probe} at a Truffle AST node. * <p> - * 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. * <p> * <strong>Disclaimer:</strong> experimental interface under development. Really! */
--- 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. * <p> * <strong>WARNING:</strong> 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 */
--- 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}. * <p> * <strong>Disclaimer:</strong> experimental interface under development. */
--- 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 (<em>empty set</em> if none). + * In which user-sensible categories has this node been tagged (<em>empty set</em> if none). */ Iterable<SyntaxTag> getSyntaxTags();
--- 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<SyntaxTag> getSyntaxTags() { return tags; }
--- 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<Probe> findProbesTaggedAs(SyntaxTag tag) { final List<Probe> probes = new ArrayList<>();