Cleaning up javadoc.

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) {
 

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) => _|_
+	 * <pre>
+	 * some(v')	if p(v) => v' 
+	 * none	  	if p(v) => _|_
+	 * </pre>
 	 */
 	public abstract Expression match(Var u);
 	public abstract Expression bind(Var u, Expression g);
@@ -165,12 +167,7 @@ public static Expression lift(List<Expression> 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
+	 * <p><code>opbind(f,t,g) = f >s> ( (isSome(s) >t> g) >u> some(u) | isNone(s) >> none )</code>
 	 */
 	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) {
 

OrcJava/src/orc/ast/oil/Expr.java

@@ -56,9 +56,8 @@ public Set<Var> 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<Integer> indices, int depth) {
 		return;

OrcJava/src/orc/ast/simple/Expression.java

@@ -59,7 +59,6 @@ public Expression suball(Map<NamedVar, ? extends Argument> m)
 
 	/**
 	 * Find the set of all unbound Vars (note: not FreeVars) in this expression.
-	 * @return
 	 */
 	public abstract Set<Var> vars();
 

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())

OrcJava/src/orc/package-info.java

@@ -5,6 +5,6 @@
  * integrated with arbitrary Java code, we can afford to
  * bend naming conventions.
  * 
- * <p>The {@link Orc} class is the main interface to users.
+ * <p>The {@link orc.Orc} class is the main interface to users.
  */
 package orc;

OrcJava/src/orc/runtime/Args.java

@@ -209,7 +209,6 @@ public interface NumericBinaryOperator<T> {
 	/**
 	 * Dispatch a binary operator based on the widest
 	 * type of two numbers.
-	 * @return
 	 */
 	public static <T> T applyNumericOperator(Number a, Number b, NumericBinaryOperator<T> op) {
 		if (a instanceof BigDecimal) {
@@ -257,7 +256,6 @@ public static <T> T applyNumericOperator(Number a, Number b, NumericBinaryOperat
 
 	/**
 	 * Dispatch a unary operator based on the type of a number.
-	 * @return
 	 */
 	public static <T> T applyNumericOperator(Number a, NumericUnaryOperator<T> op) {
 		if (a instanceof BigDecimal) {

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();

OrcJava/src/orc/runtime/Token.java

@@ -145,8 +145,8 @@ public Token setEnv(Env<Future> 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,19 +158,14 @@ 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<Future> env, Token returnToken) {
 		return new Token(node, env, returnToken, group, region, null, engine);
 	}
 
 	/**
 	 * 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);		

OrcJava/src/orc/runtime/nodes/Call.java

@@ -34,7 +34,6 @@ public Call(Arg caller, List<Arg> 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) {
 

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;
 	}

OrcJava/src/orc/runtime/nodes/Defs.java

@@ -44,8 +44,6 @@ public Defs(List<Def> defs, Node next, Set<Var> 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) {
 

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) {
 		/*

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) {
 		/*

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) {
 

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) {
 		/*

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();

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();
 	}
 

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<Future> args, Node nextNode) throws TokenException;
 

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<Future> args, Node nextNode) throws ArityMismatchException {
 

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;