From 7efb7b9e997e0977c8343718cd8b5149805ea57b Mon Sep 17 00:00:00 2001 From: Ben Culkin Date: Sat, 13 Mar 2021 09:11:12 -0500 Subject: Add more documentation Also, changed my mind on the way DiePool and its implementations should be structured. The implementations go in the die pool file as internal classes, because nobody should particularly care the specifics about their die pool, only that it does what it says it should --- .../java/bjc/dicelang/neodice/DieBoxException.java | 36 ++++++++++++++++++++-- .../bjc/dicelang/neodice/commands/BindCommand.java | 5 +++ .../neodice/statements/ArrayStatementValue.java | 16 +++++++++- .../neodice/statements/BooleanStatementValue.java | 7 +++++ .../neodice/statements/DiePoolStatementValue.java | 13 ++++++++ .../neodice/statements/DieStatementValue.java | 13 ++++++++ .../neodice/statements/StatementValue.java | 21 +++++++++++++ 7 files changed, 108 insertions(+), 3 deletions(-) (limited to 'dice/src/example/java/bjc/dicelang/neodice') diff --git a/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java b/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java index efa3d54..e1de67e 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java +++ b/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java @@ -1,28 +1,60 @@ package bjc.dicelang.neodice; +/** + * The exception thrown when something goes wrong with diebox. + * @author Ben Culkin + * + */ public class DieBoxException extends RuntimeException { private static final long serialVersionUID = 1851356458656622896L; + /** Create a new exception */ public DieBoxException() { super(); } + /** + * Create a new exception with a given message. + * + * @param message The message for the exception. + */ public DieBoxException(String message) { super(message); } + /** + * Create a new exception with a given formatted message. + * + * @param format The format string. + * @param args The format arguments. + */ public DieBoxException(String format, Object... args) { super(String.format(format, args)); } + /** + * Create a new diebox exception with a cause. + * @param cause The cause of this exception. + */ public DieBoxException(Throwable cause) { super(cause); } - + + /** + * Create a new diebox exception with a cause and message. + * @param cause The cause of this exception. + * @param message The message for the exception. + */ public DieBoxException(Throwable cause, String message) { super(message, cause); } - + + /** + * Create a new diebox exception with a cause and formatted message. + * @param cause The cause of this exception. + * @param format The format string. + * @param args The format arguments. + */ public DieBoxException(Throwable cause, String format, Object... args) { super(String.format(format, args), cause); } diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java index 5091c4b..8664379 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java +++ b/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java @@ -7,6 +7,11 @@ import java.util.*; import bjc.dicelang.neodice.*; import bjc.dicelang.neodice.statements.*; +/** + * This command binds a name to a variable slot. + * @author Ben Culkin + * + */ public class BindCommand implements Command { @Override public StatementValue execute(Iterator words, DieBoxCLI state) { diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java index 66e14ad..1a54ca5 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java +++ b/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java @@ -4,10 +4,24 @@ import static bjc.dicelang.neodice.statements.StatementValue.Type.*; import java.util.*; +/** + * A statement value which represents an array of statement values. + * @author Ben Culkin + * + * @param The contained type of value. + */ public class ArrayStatementValue extends StatementValue { - public final Type elementType; + /** The type of the contained values. */ + public final Type elementType; + /** The contained values. */ public final ElementType[] values; + /** + * Create a new array statement value. + * + * @param elementType The type of the contained values. + * @param values The contained values. + */ @SafeVarargs public ArrayStatementValue(Type elementType, ElementType... values) { super(ARRAY); diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java index ba89893..aef912b 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java +++ b/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java @@ -4,10 +4,17 @@ import static bjc.dicelang.neodice.statements.StatementValue.Type.*; import java.util.*; +/** + * Represents the boolean type for diebox. + * @author Ben Culkin + * + */ public class BooleanStatementValue extends StatementValue { private boolean value; + /** The true boolean instance. */ public static final BooleanStatementValue TRUE_INST = new BooleanStatementValue(true); + /** The false boolean instance. */ public static final BooleanStatementValue FALSE_INST = new BooleanStatementValue(false); private BooleanStatementValue(boolean value) { diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java index 8d7c1f4..114475c 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java +++ b/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java @@ -6,10 +6,23 @@ import java.util.*; import bjc.dicelang.neodice.*; +/** + * A StatementValue that represesnts a die pool + * @author Ben Culkin + * + */ public class DiePoolStatementValue extends StatementValue { + /** The type of the contained value. */ public final Type elementType; + /** The die pool itself. */ public final DiePool value; + /** + * Create a new diepool value. + * + * @param elementType The contained type. + * @param value The die pool itself. + */ public DiePoolStatementValue(Type elementType, DiePool value) { super(DIEPOOL); diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java index f9a8d1e..5662a59 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java +++ b/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java @@ -6,10 +6,23 @@ import java.util.*; import bjc.dicelang.neodice.*; +/** + * A StatementValue that represents a die. + * @author Ben Culkin + * + */ public class DieStatementValue extends StatementValue { + /** The type of values this die rolls. */ public final Type sideType; + /** The die itself. */ public final Die value; + /** + * Create a new die StatementValue. + * + * @param sideType The type of value this die rolls. + * @param value The die itself. + */ public DieStatementValue(Type sideType, Die value) { super(DIE); diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java index de796e5..d804a10 100644 --- a/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java +++ b/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java @@ -2,20 +2,41 @@ package bjc.dicelang.neodice.statements; import java.util.*; +/** + * Represents a value for diebox, as a base class. + * @author Ben Culkin + * + */ public abstract class StatementValue { + /** + * The type of the value. + * @author Ben Culkin + * + */ public static enum Type { + /** The 'void' value. There is only one value of this type. */ VOID, + /** The 'boolean' type. There is one true value, and one false value. */ BOOLEAN, + /** Represents an integer. */ INTEGER, + /** Represents a single die. */ DIE, + /** Represents a pool of dice. */ DIEPOOL, + /** Represents an array of some type. */ ARRAY, } + /** The type of this value. */ public final Type type; + /** + * Create a new statement value. + * @param type The type of the value. + */ protected StatementValue(Type type) { this.type = type; } -- cgit v1.2.3