From 59af5fc341d7ef8d4ddd4870b0bd9bbf97605466 Mon Sep 17 00:00:00 2001 From: Adrian Quark Date: Wed, 16 Jul 2008 23:18:33 +0000 Subject: [PATCH] Cleaning up javadoc. --- OrcJava/src/orc/Orc.java | 5 ++++- .../src/orc/ast/extended/pattern/Pattern.java | 14 +++++-------- OrcJava/src/orc/ast/oil/Expr.java | 5 ++--- OrcJava/src/orc/ast/simple/Expression.java | 1 - OrcJava/src/orc/ast/sites/Site.java | 1 - OrcJava/src/orc/package-info.java | 2 +- OrcJava/src/orc/runtime/Args.java | 2 -- OrcJava/src/orc/runtime/OrcEngine.java | 4 ---- OrcJava/src/orc/runtime/Token.java | 16 +++++--------- OrcJava/src/orc/runtime/nodes/Call.java | 1 - OrcJava/src/orc/runtime/nodes/Def.java | 21 ++++++------------- OrcJava/src/orc/runtime/nodes/Defs.java | 2 -- OrcJava/src/orc/runtime/nodes/Fork.java | 1 - OrcJava/src/orc/runtime/nodes/Return.java | 1 - OrcJava/src/orc/runtime/nodes/Semi.java | 1 - OrcJava/src/orc/runtime/nodes/Store.java | 1 - OrcJava/src/orc/runtime/nodes/Subgoal.java | 1 - OrcJava/src/orc/runtime/sites/core/Let.java | 7 +++---- OrcJava/src/orc/runtime/values/Callable.java | 2 -- OrcJava/src/orc/runtime/values/Closure.java | 1 - OrcJava/src/orc/runtime/values/GroupCell.java | 1 - 21 files changed, 26 insertions(+), 64 deletions(-) diff --git a/OrcJava/src/orc/Orc.java b/OrcJava/src/orc/Orc.java index 011c23d0e..dc5f4ab91 100644 --- a/OrcJava/src/orc/Orc.java +++ b/OrcJava/src/orc/Orc.java @@ -185,10 +185,12 @@ protected static Node compile(Reader source, Node target, Config cfg) { return null; } + /** @deprecated */ public static OrcInstance runEmbedded(String source) { return runEmbedded(new File(source)); } + /** @deprecated */ public static OrcInstance runEmbedded(File source) { try { return runEmbedded(new FileReader(source)); @@ -199,6 +201,7 @@ public static OrcInstance runEmbedded(File source) { } } + /** @deprecated */ public static OrcInstance runEmbedded(Reader source) { return runEmbedded(source, new Config()); } @@ -208,9 +211,9 @@ public static OrcInstance runEmbedded(Reader source) { * Start a new Orc engine running this program in a separate thread. * Returns an OrcInstance object with information about the running instance. * + * @deprecated * @param source * @param cfg - * @return */ public static OrcInstance runEmbedded(Reader source, Config cfg) { diff --git a/OrcJava/src/orc/ast/extended/pattern/Pattern.java b/OrcJava/src/orc/ast/extended/pattern/Pattern.java index fad7fe555..14769d8dd 100644 --- a/OrcJava/src/orc/ast/extended/pattern/Pattern.java +++ b/OrcJava/src/orc/ast/extended/pattern/Pattern.java @@ -52,8 +52,10 @@ public abstract class Pattern { /** * @param f The source expression for values to be matched * @return A new expression publishing, for each publication !v of f, - * some(v') if p(v) => v' - * none if p(v) => _|_ + * 
+	 * some(v')	if p(v) => v' 
+	 * none	  	if p(v) => _|_
+	 *
*/ public abstract Expression match(Var u); public abstract Expression bind(Var u, Expression g); @@ -165,12 +167,7 @@ public static Expression lift(List es) { * Create an expression computing a monadic bind for options. * I'd really rather be using Haskell here. * - * opbind(f,t,g) = f >s> ( (isSome(s) >t> g) >u> some(u) | isNone(s) >> none ) - * - * @param l - * @param t - * @param r - * @return + *

opbind(f,t,g) = f >s> ( (isSome(s) >t> g) >u> some(u) | isNone(s) >> none ) */ public static Expression opbind(Expression f, Var t, Expression g) { @@ -188,7 +185,6 @@ public static Expression opbind(Expression f, Var t, Expression g) { * Filter an expression by piping its publications through isSome. * Values some(v) will publish v, values none will be ignored. * @param e - * @return */ public static Expression filter(Expression e) { diff --git a/OrcJava/src/orc/ast/oil/Expr.java b/OrcJava/src/orc/ast/oil/Expr.java index 790b56ba5..bc2ecf775 100644 --- a/OrcJava/src/orc/ast/oil/Expr.java +++ b/OrcJava/src/orc/ast/oil/Expr.java @@ -56,9 +56,8 @@ public Set freeVars() { * which contain variables or subexpressions override this * behavior. * - * @param vars The index set accumulator. - * @param depth The minimum index for a free variable. - * @return + * @param indices The index set accumulator. + * @param depth The minimum index for a free variable. */ public void addIndices(Set indices, int depth) { return; diff --git a/OrcJava/src/orc/ast/simple/Expression.java b/OrcJava/src/orc/ast/simple/Expression.java index 76c7c2e6a..f8794b543 100644 --- a/OrcJava/src/orc/ast/simple/Expression.java +++ b/OrcJava/src/orc/ast/simple/Expression.java @@ -59,7 +59,6 @@ public Expression suball(Map m) /** * Find the set of all unbound Vars (note: not FreeVars) in this expression. - * @return */ public abstract Set vars(); diff --git a/OrcJava/src/orc/ast/sites/Site.java b/OrcJava/src/orc/ast/sites/Site.java index 66eaacb05..8ee02b994 100644 --- a/OrcJava/src/orc/ast/sites/Site.java +++ b/OrcJava/src/orc/ast/sites/Site.java @@ -81,7 +81,6 @@ public static Site buildCoreSite(String primitive) { * and their locations are equal. * * @param that The site to which to compare. - * @return */ public boolean equals(Site that) { return ( this.getLocation().equals(that.getLocation()) diff --git a/OrcJava/src/orc/package-info.java b/OrcJava/src/orc/package-info.java index 54cfffc8c..e3dbb25e1 100644 --- a/OrcJava/src/orc/package-info.java +++ b/OrcJava/src/orc/package-info.java @@ -5,6 +5,6 @@ * integrated with arbitrary Java code, we can afford to * bend naming conventions. * - *

The {@link Orc} class is the main interface to users. + *

The {@link orc.Orc} class is the main interface to users. */ package orc; \ No newline at end of file diff --git a/OrcJava/src/orc/runtime/Args.java b/OrcJava/src/orc/runtime/Args.java index cf2353d50..371251390 100644 --- a/OrcJava/src/orc/runtime/Args.java +++ b/OrcJava/src/orc/runtime/Args.java @@ -209,7 +209,6 @@ public interface NumericBinaryOperator { /** * Dispatch a binary operator based on the widest * type of two numbers. - * @return */ public static T applyNumericOperator(Number a, Number b, NumericBinaryOperator op) { if (a instanceof BigDecimal) { @@ -257,7 +256,6 @@ public static T applyNumericOperator(Number a, Number b, NumericBinaryOperat /** * Dispatch a unary operator based on the type of a number. - * @return */ public static T applyNumericOperator(Number a, NumericUnaryOperator op) { if (a instanceof BigDecimal) { diff --git a/OrcJava/src/orc/runtime/OrcEngine.java b/OrcJava/src/orc/runtime/OrcEngine.java index 91030befa..580e22c9b 100644 --- a/OrcJava/src/orc/runtime/OrcEngine.java +++ b/OrcJava/src/orc/runtime/OrcEngine.java @@ -170,14 +170,10 @@ public void pub(Value v) { } /** - * * A token owned by this engine has encountered an exception. * The token dies, remaining silent and leaving the execution, * and then calls this method so that the engine can report or * otherwise handle the failure. - * - * @param t - * @param probme */ public void tokenError(Token t, TokenException problem) { System.out.println(); diff --git a/OrcJava/src/orc/runtime/Token.java b/OrcJava/src/orc/runtime/Token.java index 4cdfe3d27..37d342564 100644 --- a/OrcJava/src/orc/runtime/Token.java +++ b/OrcJava/src/orc/runtime/Token.java @@ -145,8 +145,8 @@ public Token setEnv(Env e) { /** * Move to a node node - * @param node the node to move to - * @return returns self + * @param node the node to move to + * @return returns self */ public Token move(Node node) { this.node = node; @@ -158,11 +158,6 @@ public Token move(Node node) { * Create a copy of this token with the same dynamic characteristics, * but executing at a new point in the graph with a different environment. * Set the new caller's token to the token provided. - * - * @param node - * @param env - * @param caller - * @return */ public Token callcopy(Node node, Env env, Token returnToken) { return new Token(node, env, returnToken, group, region, null, engine); @@ -170,7 +165,7 @@ public Token callcopy(Node node, Env env, Token returnToken) { /** * Create a copy of the token - * @return new token + * @return new token */ public Token copy() { return new Token(node, env, caller, group, region, result, engine); @@ -195,12 +190,11 @@ public Token unwind(int width) { env = env.unwind(width); return this; } - /** * Lookup a variable in the environment - * @param var variable name - * @return value, or an error if the variable is undefined + * @param var variable name + * @return value, or an error if the variable is undefined */ public Future lookup(Arg a) { return a.resolve(env); diff --git a/OrcJava/src/orc/runtime/nodes/Call.java b/OrcJava/src/orc/runtime/nodes/Call.java index 45aefd879..e3e8ed83e 100644 --- a/OrcJava/src/orc/runtime/nodes/Call.java +++ b/OrcJava/src/orc/runtime/nodes/Call.java @@ -34,7 +34,6 @@ public Call(Arg caller, List args, Node next) { /** * Looks up the function to be called, then creates a call * token using the argument expressions. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { diff --git a/OrcJava/src/orc/runtime/nodes/Def.java b/OrcJava/src/orc/runtime/nodes/Def.java index b960c06a2..5b131dc60 100644 --- a/OrcJava/src/orc/runtime/nodes/Def.java +++ b/OrcJava/src/orc/runtime/nodes/Def.java @@ -5,30 +5,21 @@ /** * - * A unit of syntax that encapsulates an expression definition. + * A unit of syntax that encapsulates an expression definition. * - * Groups of mutually recursive definitions are embedded in the execution graph by a Defs node. + * Groups of mutually recursive definitions are embedded in the execution graph + * by a Defs node. * * @author dkitchin - * + * */ public class Def { public int arity; public Node body; - - /** - * Note that the constructor takes a bound Var as a name parameter. This is because the - * binding of expression names occurs at the level of mutually recursive groups, not at - * the level of the individual definitions. - * - * @param name - * @param formals - * @param body - */ - public Def(int arity, Node body) - { + + public Def(int arity, Node body) { this.arity = arity; this.body = body; } diff --git a/OrcJava/src/orc/runtime/nodes/Defs.java b/OrcJava/src/orc/runtime/nodes/Defs.java index 40f805944..0670751fa 100644 --- a/OrcJava/src/orc/runtime/nodes/Defs.java +++ b/OrcJava/src/orc/runtime/nodes/Defs.java @@ -44,8 +44,6 @@ public Defs(List defs, Node next, Set freeset) * Closures created in this way are protected by a PartialValue object, * preventing them from being used in argument position until all unbound * vars in all definition bodies become bound. - * - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { diff --git a/OrcJava/src/orc/runtime/nodes/Fork.java b/OrcJava/src/orc/runtime/nodes/Fork.java index 0244b233d..f874bf60e 100644 --- a/OrcJava/src/orc/runtime/nodes/Fork.java +++ b/OrcJava/src/orc/runtime/nodes/Fork.java @@ -21,7 +21,6 @@ public Fork(Node left, Node right) { /** * The input token is activated on the right node, * and a copy is activated on the left node. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { /* diff --git a/OrcJava/src/orc/runtime/nodes/Return.java b/OrcJava/src/orc/runtime/nodes/Return.java index 0692da2f2..02de631ac 100644 --- a/OrcJava/src/orc/runtime/nodes/Return.java +++ b/OrcJava/src/orc/runtime/nodes/Return.java @@ -19,7 +19,6 @@ public class Return extends Node { * The caller token points to the node after the call. * The caller is then copied, the result of the caller is set, and * the token is activated. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { /* diff --git a/OrcJava/src/orc/runtime/nodes/Semi.java b/OrcJava/src/orc/runtime/nodes/Semi.java index 0c2ceb7b3..2f3220a0c 100644 --- a/OrcJava/src/orc/runtime/nodes/Semi.java +++ b/OrcJava/src/orc/runtime/nodes/Semi.java @@ -23,7 +23,6 @@ public Semi(Node left, Node right) { /** * The input token is activated on the right node, * and a copy is activated on the left node. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { diff --git a/OrcJava/src/orc/runtime/nodes/Store.java b/OrcJava/src/orc/runtime/nodes/Store.java index 4215d422b..97a064aa1 100644 --- a/OrcJava/src/orc/runtime/nodes/Store.java +++ b/OrcJava/src/orc/runtime/nodes/Store.java @@ -21,7 +21,6 @@ public class Store extends Node { * of the input token. * As a side effect of setting the value of a group, a pull variable * becomes bound and the execution of the group is terminated. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { /* diff --git a/OrcJava/src/orc/runtime/nodes/Subgoal.java b/OrcJava/src/orc/runtime/nodes/Subgoal.java index 41aa3fa0c..10a81500d 100644 --- a/OrcJava/src/orc/runtime/nodes/Subgoal.java +++ b/OrcJava/src/orc/runtime/nodes/Subgoal.java @@ -28,7 +28,6 @@ public Subgoal(Node left, Node right) { * associated with this group cell for execution of the * left side of the pull. The token is then moved to the * right side and it is associated with the new group. - * @see orc.runtime.nodes.Node#process(orc.runtime.Token, orc.runtime.OrcEngine) */ public void process(Token t) { GroupCell cell = t.getGroup().createCell(); diff --git a/OrcJava/src/orc/runtime/sites/core/Let.java b/OrcJava/src/orc/runtime/sites/core/Let.java index ec9b6da00..0de14888c 100644 --- a/OrcJava/src/orc/runtime/sites/core/Let.java +++ b/OrcJava/src/orc/runtime/sites/core/Let.java @@ -15,12 +15,11 @@ public class Let extends Site { private static final long serialVersionUID = 1L; /** - * Outputs a single value or creates a tuple. - * @see orc.runtime.sites.Site#callSite(java.lang.Object[], orc.runtime.Token, orc.runtime.OrcEngine) + * Outputs a single value or creates a tuple. */ public void callSite(Args args, Token caller) { - - // Note that a let does not resume like a normal site call; it sets the result and activates directly + // Note that a let does not resume like a normal site call; it sets the result and activates directly; + // This is necessary to preserve the "immediate" semantics of Let. caller.setResult(args.condense()).activate(); } diff --git a/OrcJava/src/orc/runtime/values/Callable.java b/OrcJava/src/orc/runtime/values/Callable.java index 0b442bb15..601f9696d 100644 --- a/OrcJava/src/orc/runtime/values/Callable.java +++ b/OrcJava/src/orc/runtime/values/Callable.java @@ -17,11 +17,9 @@ public interface Callable { /** * Create a call to a callable value - * @param label name (used for debugging) * @param caller token for which the call is being made: points to the call node * @param args argument list * @param nextNode next node after the call node, to which the result should be sent - * @param engine Orc engine */ void createCall(Token caller, List args, Node nextNode) throws TokenException; diff --git a/OrcJava/src/orc/runtime/values/Closure.java b/OrcJava/src/orc/runtime/values/Closure.java index 586d9893a..861934c8a 100644 --- a/OrcJava/src/orc/runtime/values/Closure.java +++ b/OrcJava/src/orc/runtime/values/Closure.java @@ -42,7 +42,6 @@ public Closure(int arity, Node body, Env env) { * The caller of the new token is normally a token point to right * after the call. However, for tail-calls the existing caller * is reused, rather than creating a new intermediate stack frame. - * @see orc.runtime.values.Callable#createCall(java.lang.String, orc.runtime.Token, java.util.List, orc.runtime.nodes.Node) */ public void createCall(Token callToken, List args, Node nextNode) throws ArityMismatchException { diff --git a/OrcJava/src/orc/runtime/values/GroupCell.java b/OrcJava/src/orc/runtime/values/GroupCell.java index 1fa41888b..5bdbf2834 100644 --- a/OrcJava/src/orc/runtime/values/GroupCell.java +++ b/OrcJava/src/orc/runtime/values/GroupCell.java @@ -57,7 +57,6 @@ public GroupCell createCell() { * When the value is bound, all subgroups are killed * and all waiting tokens are activated. * @param value the value for the group - * @param engine engine */ public void setValue(Value value) { this.value = value;