From a04742085e03edfd6cb800074fd177f05824c85b Mon Sep 17 00:00:00 2001 From: Brady Date: Fri, 27 Sep 2019 09:54:55 -0500 Subject: [PATCH] Add documentation to datatypes --- .../utils/command/datatypes/IDatatype.java | 16 +++++++++++++--- .../utils/command/datatypes/IDatatypeFor.java | 19 +++++++++++++++++++ .../command/datatypes/IDatatypePost.java | 7 +++++++ 3 files changed, 39 insertions(+), 3 deletions(-) diff --git a/src/api/java/baritone/api/utils/command/datatypes/IDatatype.java b/src/api/java/baritone/api/utils/command/datatypes/IDatatype.java index 2a0696f2..8c155fb6 100644 --- a/src/api/java/baritone/api/utils/command/datatypes/IDatatype.java +++ b/src/api/java/baritone/api/utils/command/datatypes/IDatatype.java @@ -24,6 +24,16 @@ import baritone.api.utils.command.helpers.arguments.ArgConsumer; import java.util.stream.Stream; /** + * An {@link IDatatype} is similar to an {@link IArgParser} in the sense that it is capable of consuming an argument + * to transform it into a usable form as the code desires. + *

+ * A fundamental difference is that an {@link IDatatype} is capable of consuming multiple arguments. For example, + * {@link RelativeBlockPos} is an {@link IDatatypePost} which requires at least 3 {@link RelativeCoordinate} arguments + * to be specified. + *

+ * Another difference is that an {@link IDatatype} can be tab-completed, providing comprehensive auto completion + * that can substitute based on existing input or provide possibilities for the next piece of input. + * * @see IDatatypeContext * @see IDatatypeFor * @see IDatatypePost @@ -31,12 +41,12 @@ import java.util.stream.Stream; public interface IDatatype { /** + * Attempts to complete missing or partial input provided through the {@link ArgConsumer} provided by + * {@link IDatatypeContext#getConsumer()} in order to aide the user in executing commands. + *

* One benefit over datatypes over {@link IArgParser}s is that instead of each command trying to guess what values * the datatype will accept, or simply not tab completing at all, datatypes that support tab completion can provide * accurate information using the same methods used to parse arguments in the first place. - *

- * See {@link RelativeFile} for a very advanced example of tab completion. You wouldn't want this pasted into every - * command that uses files - right? Right? * * @param ctx The argument consumer to tab complete * @return A stream representing the strings that can be tab completed. DO NOT INCLUDE SPACES IN ANY STRINGS. diff --git a/src/api/java/baritone/api/utils/command/datatypes/IDatatypeFor.java b/src/api/java/baritone/api/utils/command/datatypes/IDatatypeFor.java index 3168702a..4f0f4200 100644 --- a/src/api/java/baritone/api/utils/command/datatypes/IDatatypeFor.java +++ b/src/api/java/baritone/api/utils/command/datatypes/IDatatypeFor.java @@ -19,7 +19,26 @@ package baritone.api.utils.command.datatypes; import baritone.api.utils.command.exception.CommandException; +import java.util.function.Supplier; + +/** + * An {@link IDatatype} which acts as a {@link Supplier}, in essence. The only difference + * is that it requires an {@link IDatatypeContext} to be provided due to the expectation that + * implementations of {@link IDatatype} are singletons. + */ public interface IDatatypeFor extends IDatatype { + /** + * Consumes the desired amount of arguments from the specified {@link IDatatypeContext}, and + * then returns the parsed value. This method will more than likely return a {@link IllegalArgumentException} + * if the expected input does not conform to a parseable value. As far as a {@link CommandException} being + * thrown is concerned, see the note below for specifics. + * + * @see IDatatypeContext + * + * @param ctx The context + * @return The parsed data-type + * @throws CommandException If there was an issue parsing using another type or arguments could not be polled. + */ T get(IDatatypeContext ctx) throws CommandException; } diff --git a/src/api/java/baritone/api/utils/command/datatypes/IDatatypePost.java b/src/api/java/baritone/api/utils/command/datatypes/IDatatypePost.java index 3e1e70be..2e4cc47a 100644 --- a/src/api/java/baritone/api/utils/command/datatypes/IDatatypePost.java +++ b/src/api/java/baritone/api/utils/command/datatypes/IDatatypePost.java @@ -19,6 +19,13 @@ package baritone.api.utils.command.datatypes; import baritone.api.utils.command.exception.CommandException; +import java.util.function.Function; + +/** + * An {@link IDatatype} which acts as a {@link Function}, in essence. The only difference + * is that it requires an {@link IDatatypeContext} to be provided due to the expectation that + * implementations of {@link IDatatype} are singletons. + */ public interface IDatatypePost extends IDatatype { /**