diff --git a/src/main/java/com/sk89q/worldedit/expression/Expression.java b/src/main/java/com/sk89q/worldedit/expression/Expression.java
index 236120838..d94045ea9 100644
--- a/src/main/java/com/sk89q/worldedit/expression/Expression.java
+++ b/src/main/java/com/sk89q/worldedit/expression/Expression.java
@@ -32,6 +32,30 @@ import com.sk89q.worldedit.expression.runtime.EvaluationException;
import com.sk89q.worldedit.expression.runtime.RValue;
import com.sk89q.worldedit.expression.runtime.Variable;
+/**
+ * Compiles and evaluates expressions.
+ *
+ * Supported operators:
+ * Logical: &&, ||, ! (unary)
+ * Bitwise: ~ (unary), >>, <<
+ * Arithmetic: +, -, *, /, % (modulo), ^ (power), - (unary), --, ++ (prefix only)
+ * Comparison: <=, >=, >, <, ==, !=, ~= (near)
+ *
+ * Supported functions: abs, acos, asin, atan, atan2, cbrt, ceil, cos, cosh, exp, floor, ln, log, log10, max, max, min, min, rint, round, sin, sinh, sqrt, tan, tanh
+ *
+ * Constants: e, pi
+ *
+ * To compile an equation, run Expression.compile("expression here", "var1", "var2"...)
+ * If you wish to run the equation multiple times, you can then optimize it, by calling myExpression.optimize();
+ * You can then run the equation as many times as you want by calling myExpression.evaluate(var1, var2...)
+ * You do not need to pass values for all variables specified while compiling.
+ * To query variables after evaluation, you can use myExpression.getVariable("variable name").
+ * To get a value out of these, use myVariable.getValue()
+ *
+ * Variables are also supported and can be set either by passing values to evaluate
+ *
+ * @author TomyLobo
+ */
public class Expression {
private final Map variables = new HashMap();
private final String[] variableNames;
diff --git a/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java b/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
index 503bfb648..00177bed8 100644
--- a/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression;
+/**
+ * Thrown when there's a problem during any stage of the expression compilation or evaluation.
+ *
+ * @author TomyLobo
+ */
public class ExpressionException extends Exception {
private static final long serialVersionUID = 1L;
diff --git a/src/main/java/com/sk89q/worldedit/expression/Identifiable.java b/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
index d904eea6b..331256ca5 100644
--- a/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
+++ b/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression;
+/**
+ * A common superinterface for everything passed to parser processors.
+ *
+ * @author TomyLobo
+ */
public interface Identifiable {
/**
* Returns a character that helps identify the token, pseudo-token or invokable in question.
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java b/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
index 9851c9341..a97f70bea 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
@@ -31,6 +31,13 @@ import java.util.regex.Pattern;
import com.sk89q.worldedit.expression.lexer.tokens.*;
+/**
+ * Processes a string into a list of tokens.
+ *
+ * Tokens can be numbers, identifiers, operators and assorted other characters.
+ *
+ * @author TomyLobo
+ */
public class Lexer {
private final String expression;
private int position = 0;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java b/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
index dc893088d..b403979fa 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.lexer;
import com.sk89q.worldedit.expression.ExpressionException;
+/**
+ * Thrown when the lexer encounters a problem.
+ *
+ * @author TomyLobo
+ */
public class LexerException extends ExpressionException {
private static final long serialVersionUID = 1L;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
index 36dfe657d..ae91a8bff 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.lexer.tokens;
+/**
+ * A single character that doesn't fit any of the other token categories.
+ *
+ * @author TomyLobo
+ */
public class CharacterToken extends Token {
public final char character;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
index 790824e9e..a4c7437d3 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.lexer.tokens;
+/**
+ * An identifier
+ *
+ * @author TomyLobo
+ */
public class IdentifierToken extends Token {
public final String value;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
index d73d70db8..e76ace405 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.lexer.tokens;
+/**
+ * A keyword
+ *
+ * @author TomyLobo
+ */
public class KeywordToken extends Token {
public final String value;
@@ -29,7 +34,7 @@ public class KeywordToken extends Token {
@Override
public char id() {
- return 'i';
+ return 'k';
}
@Override
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
index 1f4858e64..e0b72d18c 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.lexer.tokens;
+/**
+ * A number
+ *
+ * @author TomyLobo
+ */
public class NumberToken extends Token {
public final double value;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
index 655c2e65d..1108f2c08 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.lexer.tokens;
+/**
+ * A unary or binary operator.
+ *
+ * @author TomyLobo
+ */
public class OperatorToken extends Token {
public final String operator;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
index 4957a3499..b01743814 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.lexer.tokens;
import com.sk89q.worldedit.expression.Identifiable;
+/**
+ * A token. The lexer generates these to make the parser's job easier.
+ *
+ * @author TomyLobo
+ */
public abstract class Token implements Identifiable {
private final int position;
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java b/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
index 5429bb667..d84f49854 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
@@ -34,6 +34,13 @@ import com.sk89q.worldedit.expression.runtime.Constant;
import com.sk89q.worldedit.expression.runtime.Functions;
import com.sk89q.worldedit.expression.runtime.RValue;
+/**
+ * Processes a list of tokens into an executable tree.
+ *
+ * Tokens can be numbers, identifiers, operators and assorted other characters.
+ *
+ * @author TomyLobo
+ */
public class Parser {
private final class NullToken extends Token {
private NullToken(int position) {
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java b/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
index 03b104e05..8203369f1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.parser;
import com.sk89q.worldedit.expression.ExpressionException;
+/**
+ * Thrown when the parser encounters a problem.
+ *
+ * @author TomyLobo
+ */
public class ParserException extends ExpressionException {
private static final long serialVersionUID = 1L;
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java b/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
index 44fe216e9..5a49ffaa1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
@@ -13,6 +13,11 @@ import com.sk89q.worldedit.expression.runtime.RValue;
import com.sk89q.worldedit.expression.runtime.Operators;
import com.sk89q.worldedit.expression.runtime.Sequence;
+/**
+ * Helper classfor Parser. Contains processors for statements and operators.
+ *
+ * @author TomyLobo
+ */
public final class ParserProcessors {
private static final Map unaryOpMap = new HashMap();
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java b/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
index d710ffe9c..2a67bcde8 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
@@ -2,6 +2,11 @@ package com.sk89q.worldedit.expression.parser;
import com.sk89q.worldedit.expression.lexer.tokens.OperatorToken;
+/**
+ * The parser uses this pseudo-token to mark operators as prefix operators.
+ *
+ * @author TomyLobo
+ */
public class PrefixOperator extends PseudoToken {
final String operator;
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java b/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
index 43eab155f..05199be7a 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.parser;
import com.sk89q.worldedit.expression.Identifiable;
+/**
+ * A pseudo-token, inserted by the parser instead of the lexer.
+ *
+ * @author TomyLobo
+ */
public abstract class PseudoToken implements Identifiable {
private final int position;
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
index 13819b9d7..92d226134 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.runtime;
+/**
+ * A constant.
+ *
+ * @author TomyLobo
+ */
public final class Constant extends RValue {
private final double value;
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java b/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
index 4e016463e..94c6fd1a1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
@@ -2,6 +2,11 @@ package com.sk89q.worldedit.expression.runtime;
import com.sk89q.worldedit.expression.ExpressionException;
+/**
+ * Thrown when there's a problem during expression evaluation.
+ *
+ * @author TomyLobo
+ */
public class EvaluationException extends ExpressionException {
private static final long serialVersionUID = 1L;
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
index aefab8599..b9b13b78d 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
@@ -24,7 +24,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
+/**
+ * Wrapper for a Java method and its arguments (other Invokables)
+ *
+ * @author TomyLobo
+ */
public class Function extends RValue {
+ /**
+ * Add this annotation on functions that don't always return the same value for the same inputs.
+ */
@Retention(RetentionPolicy.RUNTIME)
public @interface Dynamic { }
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
index b79c44532..1a687011f 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.runtime;
import java.util.Arrays;
+/**
+ * Contains all functions that can be used in expressions.
+ *
+ * @author TomyLobo
+ */
public final class Functions {
public static final Function getFunction(int position, String name, RValue... args) throws NoSuchMethodException {
final Class>[] parameterTypes = (Class>[]) new Class[args.length];
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java b/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
index 79681d4f0..e868bd800 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.runtime;
+/**
+ * A value that can be used on the left side of an assignment.
+ *
+ * @author TomyLobo
+ */
public abstract class LValue extends RValue {
public LValue(int position) {
super(position);
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
index a68dcb523..c28e092fc 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.runtime;
+/**
+ * Contains all unary and binary operators.
+ *
+ * @author TomyLobo
+ */
public final class Operators {
public static final Function getOperator(int position, String name, RValue lhs, RValue rhs) throws NoSuchMethodException {
if (lhs instanceof LValue) {
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java b/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
index 7bc49d95e..2b8bab984 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.runtime;
import com.sk89q.worldedit.expression.Identifiable;
+/**
+ * A value that can be used on the right side of an assignment.
+ *
+ * @author TomyLobo
+ */
public abstract class RValue implements Identifiable {
private final int position;
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
index 321ac44a8..8123cc9b7 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
@@ -22,6 +22,11 @@ package com.sk89q.worldedit.expression.runtime;
import java.util.ArrayList;
import java.util.List;
+/**
+ * A sequence of operations, usually separated by semicolons in the input stream.
+ *
+ * @author TomyLobo
+ */
public class Sequence extends RValue {
private final RValue[] sequence;
@@ -33,8 +38,7 @@ public class Sequence extends RValue {
@Override
public char id() {
- // TODO Auto-generated method stub
- return 0;
+ return 's';
}
@Override
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
index af67e9e88..f61e3e428 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
@@ -19,6 +19,11 @@
package com.sk89q.worldedit.expression.runtime;
+/**
+ * A variable.
+ *
+ * @author TomyLobo
+ */
public final class Variable extends LValue {
public double value;