add documentation to several commands

yaml, webget, determine, queue, run

src/main/java/com/denizenscript/denizencore/scripts/commands/CommandRegistry.java

@@ -102,7 +102,7 @@ public void registerCoreCommands() {
         registerCoreMember(InjectCommand.class, "INJECT", "inject (locally) [<script>] (path:<name>) (instantly)", 1);
         registerCoreMember(LogCommand.class, "LOG", "log [<text>] (type:{info}/severe/warning/fine/finer/finest/none/clear) [file:<name>]", 2);
         registerCoreMember(MarkCommand.class, "MARK", "mark [<name>]", 1);
-        registerCoreMember(QueueCommand.class, "QUEUE", "queue (<queue>) [clear/stop/pause/resume/delay:<#>]", 1);
+        registerCoreMember(QueueCommand.class, "QUEUE", "queue (<queue>) [clear/stop/pause/resume/delay:<duration>]", 1);
         registerCoreMember(RandomCommand.class, "RANDOM", "random [<commands>]", 0);
         registerCoreMember(RateLimitCommand.class, "RATELIMIT", "ratelimit [<object>] [<duration>]", 2);
         registerCoreMember(ReloadCommand.class, "RELOAD", "reload", 0);
@@ -115,7 +115,7 @@ public void registerCoreCommands() {
         registerCoreMember(WaitUntilCommand.class, "WAITUNTIL", "waituntil (rate:<duration>) [<comparisons>]", 1);
         registerCoreMember(WebGetCommand.class, "WEBGET", "webget [<url>] (post:<data>) (headers:<header>/<value>|...) (timeout:<duration>/{10s}) (savefile:<path>)", 1);
         registerCoreMember(WhileCommand.class, "WHILE", "while [stop/next/<comparison tag>] [<commands>]", 1);
-        registerCoreMember(YamlCommand.class, "YAML", "yaml [create]/[load:<file>]/[loadtext:<text> (fix_formatting)]/[unload]/[savefile:<file>]/[copykey:<source key> <target key> (to_id:<name>)]/[set <key>([<#>])(:<action>):<value>] [id:<name>]", 2);
+        registerCoreMember(YamlCommand.class, "YAML", "yaml [create]/[load:<file>]/[loadtext:<text>]/[unload]/[savefile:<file>]/[copykey:<source key> <target key> (to_id:<name>)]/[set <key>([<#>])(:<action>):<value>] [id:<name>]", 2);
     }
 
     public <T extends AbstractCommand> void registerCoreMember(Class<T> cmd, String names, String hint, int args) {

src/main/java/com/denizenscript/denizencore/scripts/commands/core/WebGetCommand.java

@@ -27,11 +27,22 @@ public class WebGetCommand extends AbstractCommand implements Holdable {
     // @Group core
     //
     // @Description
-    // TODO: Document Command Details
-    // Note that while this replace URL spaces to %20, you are responsible for any other necessary URL encoding. You may want to use the element.url_encode tag for this.
-    // Optionally, specify a set of data to post to the server (changes the message from GET to POST).
-    // Optionally specify a list of headers as list of key/value pairs separated by slashes.
-    // Optionally specify a path to save the gotten file to. This will remove the 'result' entry savedata. Path is relative to server base directory.
+    // Connects to a webpage and downloads its contents, to be used via the save argument and corresponding entry tags.
+    //
+    // This should almost always be ~waited for.
+    //
+    // Note that while this will replace URL spaces to %20, you are responsible for any other necessary URL encoding.
+    // You may want to use the element.url_encode tag for this.
+    //
+    // Optionally, use "post:<data>" to specify a set of data to post to the server (changes the method from GET to POST).
+    //
+    // Optionally, use "headers:" to specify a list of headers as list of key/value pairs separated by slashes.
+    //
+    // Optionally use "savefile:" specify a path to save the gotten file to.
+    // This will remove the 'result' entry savedata.
+    // Path is relative to server base directory.
+    //
+    // Specify the "timeout:" to set how long the command should wait for a webpage to load before giving up. Defaults to 10 seconds.
     //
     // @Tags
     // <entry[saveName].failed> returns whether the webget failed.
@@ -40,7 +51,7 @@ public class WebGetCommand extends AbstractCommand implements Holdable {
     //
     // @Usage
     // Use to download the google home page.
-    // - ~webget "http://google.com" save:google
+    // - ~webget "https://google.com" save:google
     // - narrate "<entry[google].result>"
     //
     // -->

src/main/java/com/denizenscript/denizencore/scripts/commands/file/YamlCommand.java

@@ -31,7 +31,7 @@ public class YamlCommand extends AbstractCommand implements Holdable {
 
     // <--[command]
     // @Name Yaml
-    // @Syntax yaml [create]/[load:<file>]/[loadtext:<text> (fix_formatting)]/[unload]/[savefile:<file>]/[copykey:<source key> <target key> (to_id:<name>)]/[set <key>([<#>])(:<action>):<value>] [id:<name>]
+    // @Syntax yaml [create]/[load:<file>]/[loadtext:<text>]/[unload]/[savefile:<file>]/[copykey:<source key> <target key> (to_id:<name>)]/[set <key>([<#>])(:<action>):<value>] [id:<name>]
     // @Required 2
     // @Short Edits a YAML configuration file.
     // @Group file
@@ -40,12 +40,24 @@ public class YamlCommand extends AbstractCommand implements Holdable {
     // Edits a YAML configuration file.
     // This can be used for interacting with other plugins' configuration files.
     // It can also be used for storing your own script's data.
-    // TODO: Document Command Details
+    //
     // Use holdable syntax ("- ~yaml load:...") with load or savefile actions to avoid locking up the server during file IO.
     //
     // For loading and saving, the starting path is within 'plugins/Denizen'.
+    //
+    // Please note that all usages of the YAML command except for "load" and "savefile" arguments are purely in memory.
+    // That means, if you use "set" to make changes, those changes will not be saved to any file, until you use "savefile".
+    // Similarly, "create" does not create any file, instead it only creates a YAML object in RAM.
+    //
     // Note that the '.yml' extension is not automatically appended, and you will have to include that in filenames.
     //
+    // All usages of the YAML command must include the "id:" argument. This is any arbitrary name, as plaintext or from a tag,
+    // to uniquely and globally identify the YAML object in memory. This ID can only be used by one YAML object at a type.
+    // IDs are stored when "create" or "load" arguments are used, and only removed when "unload" is used.
+    // If, for example, you have a unique YAML data container per-player, you might use something like "id:myscript_<player>".
+    //
+    // For ways to use the "set" argument, refer to <@link language data actions>.
+    //
     // @Tags
     // <yaml[<idname>].contains[<path>]>
     // <yaml[<idname>].read[<path>]>

src/main/java/com/denizenscript/denizencore/scripts/commands/queue/DefineCommand.java

@@ -40,6 +40,8 @@ public class DefineCommand extends AbstractCommand {
     //
     // @Tags
     // <[<id>]> to get the value assigned to an ID
+    // <QueueTag.definition[<definition>]>
+    // <QueueTag.definitions>
     //
     // @Usage
     // Use to make complex tags look less complex, and scripts more readable.

src/main/java/com/denizenscript/denizencore/scripts/commands/queue/DetermineCommand.java

@@ -15,60 +15,53 @@ public class DetermineCommand extends AbstractCommand {
     // @Name Determine
     // @Syntax determine (passively) [<value>]
     // @Required 1
-    // @Short Sets the outcome of a world event.
+    // @Short Sets the outcome of a script.
     // @Group queue
     // @Guide https://guide.denizenscript.com/guides/first-steps/world-script.html
     //
     // @Description
-    // TODO: Document Command Details
+    // Sets the outcome of a script.
+    // The most common use case is within script events (for example, to cancel the event).
+    // This is also required for all procedure scripts.
+    // It may be useful in other cases (such as a task script that returns an result, via the save argument).
+    //
+    // By default, the determine command will end the queue (similar to <@link command stop>).
+    // If you wish to prevent this, specify the "passively" argument.
+    //
+    // To make multiple determines, simply use the determine command multiple times in a row, with the "passively" argument on each.
     //
     // @Tags
-    // TODO: Document Command Details
+    // <QueueTag.determination>
     //
     // @Usage
-    // Use to modify the result of an event
+    // Use to modify the result of an event.
     // - determine <context.message.substring[5]>
     //
     // @Usage
-    // Use to cancel an event, but continue running script commands
+    // Use to cancel an event, but continue running script commands.
     // - determine passively cancelled
     //
     // -->
 
-    // Default 'DETERMINE_NONE' value.
     public static String DETERMINE_NONE = "none";
 
 
-    //
-    // Command Singleton
-    //
-
     @Override
     public void parseArgs(ScriptEntry scriptEntry) throws InvalidArgumentsException {
 
-        //
-        // Parse the arguments
-        //
-
         for (Argument arg : scriptEntry.getProcessedArgs()) {
 
             if (arg.matches("passive", "passively")) {
                 scriptEntry.addObject("passively", new ElementTag(true));
             }
-
             else if (!scriptEntry.hasObject("outcome")) {
                 scriptEntry.addObject("outcome", arg.hasPrefix() ? new ElementTag(arg.raw_value) : arg.object);
             }
-
             else {
                 arg.reportUnhandled();
             }
         }
 
-        //
-        // Set defaults
-        //
-
         scriptEntry.defaultObject("passively", new ElementTag(false));
         scriptEntry.defaultObject("outcome", new ElementTag(DETERMINE_NONE));
     }
@@ -80,12 +73,10 @@ public void execute(ScriptEntry scriptEntry) {
         ObjectTag outcomeObj = scriptEntry.getObjectTag("outcome");
         ElementTag passively = scriptEntry.getElement("passively");
 
-        // Report!
         if (scriptEntry.dbCallShouldDebug()) {
             Debug.report(scriptEntry, getName(), outcomeObj.debug() + passively.debug() + new QueueTag(scriptEntry.getResidingQueue()).debug());
         }
 
-        // Store the outcome in the cache
         ListTag determines = scriptEntry.getResidingQueue().determinations;
         if (determines == null) {
             determines = new ListTag();
@@ -94,8 +85,8 @@ public void execute(ScriptEntry scriptEntry) {
         determines.addObject(outcomeObj);
 
         if (!passively.asBoolean()) {
-            // Stop the queue by clearing the remainder of it.
             scriptEntry.getResidingQueue().clear();
+            scriptEntry.getResidingQueue().stop();
         }
     }
 }

src/main/java/com/denizenscript/denizencore/scripts/commands/queue/QueueCommand.java

@@ -14,19 +14,32 @@ public class QueueCommand extends AbstractCommand {
 
     // <--[command]
     // @Name Queue
-    // @Syntax queue (<queue>) [clear/stop/pause/resume/delay:<#>]
+    // @Syntax queue (<queue>) [clear/stop/pause/resume/delay:<duration>]
     // @Required 1
     // @Short Modifies the current state of a script queue.
     // @Group queue
     //
     // @Description
-    // Allows queues to be modified during their run. It can also be used to modify other queues currently running
-    // Clearing a queue will remove it and not run any of the next commands in the queue.
-    // It is possible to pause a queue but it will try to finish its last command that was executed.
-    // TODO: Document Command Details
+    // Allows queues to be modified during their run. This can also be used to modify other queues currently running.
+    //
+    // Clearing a queue will remove any commands still queued within it, and thus end the queue.
+    // When trying to clear the current queue, use <@link command stop> instead.
+    //
+    // Using the "stop" argument will force the queue to immediately stop running.
+    // When trying to stop the current queue, use <@link command stop> instead.
+    //
+    // Using the "delay:<duration>" argument will cause the queue to wait for a specified duration.
+    // When trying to delay the current queue, use <@link command wait> instead.
+    //
+    // Using the "pause" argument will freeze the queue but keep it listed, waiting for a "resume" instruction.
+    // It is of course not possible to resume the current queue (as if you're running a 'queue' command, the queue can't be paused).
+    //
+    // Generally, the queue is considered a non-ideal way of doing things - that is, there's usually a better/cleaner way to achieve similar results.
+    // It's most useful within the "/ex" command for quick problem solving
+    // (eg if a script in testing gets caught in an infinite loop, you can do "/ex queue ID_HERE stop" to fix that).
     //
     // @Tags
-    // <queue> to get the current queue.
+    // <queue>
     // <QueueTag.id>
     // <QueueTag.size>
     // <queue.list>
@@ -35,10 +48,6 @@ public class QueueCommand extends AbstractCommand {
     // <ScriptTag.list_queues>
     //
     // @Usage
-    // Use to clear the current queue.
-    // - queue clear
-    //
-    // @Usage
     // Use to force-stop a given queue.
     // - queue <server.flag[OtherQueue]> clear
     //

src/main/java/com/denizenscript/denizencore/scripts/commands/queue/RunCommand.java

@@ -31,7 +31,11 @@ public class RunCommand extends AbstractCommand implements Holdable {
     //
     // Optionally, use the "path:" argument to choose a specific sub-path within a script (works well with the "locally" argument).
     //
-    // Optionally, use the "def:" argument to specify definition values to pass to the script (named via the "definitions:" script key).
+    // Optionally, use the "def:" argument to specify definition values to pass to the script,
+    // the definitions will be named via the "definitions:" script key on the script being ran,
+    // or numerically in order if that isn't specified (starting with <[1]>).
+    // To pass a list value in here as a single definition, use <@link tag ElementTag.escaped> in the run command line,
+    // and <@link tag ElementTag.unescaped> in the final task script to read it back.
     //
     // Optionally, use the "speed:" argument to specify the queue command-speed to run the target script at,
     // or use the "instantly" argument to use an instant speed (no command delay applied).
@@ -62,6 +66,12 @@ public class RunCommand extends AbstractCommand implements Holdable {
     // Use to run 'MyTask' and pass 3 definitions to it.
     // - run MyTask def:A|Second_Def|Taco
     //
+    // @Usage
+    // Use to run 'MyTask' and pass a list as a single definition.
+    // - run MyTask def:<list[a|big|list|here].escaped>
+    // # MyTask can then get the list back by doing:
+    // - define mylist:<[1].unescaped>
+    //
     // -->
 
     @Override

src/main/java/com/denizenscript/denizencore/scripts/containers/core/TaskScriptContainer.java

@@ -35,6 +35,10 @@ public class TaskScriptContainer extends ScriptContainer {
     //
     //   type: task
     //
+    //   # When intending to run a task script via <@link command run> with the "def:" argument to pass data through,
+    //   # use this "definitions" key to specify the names of the definitions (in the same order as the "def:" argument will use).
+    //   definitions: name1|name2|...
+    //
     //   script:
     //
     //   - your commands here