[#104] More docs and minor improvements

susanw1 · Aug 29, 2023 · 98af71c · 98af71c
1 parent 44633ff
commit 98af71c
Show file tree

Hide file tree

Showing 18 changed files with 184 additions and 150 deletions.
diff --git a/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/AbortCommand.java b/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/AbortCommand.java
@@ -67,10 +67,10 @@ public boolean isCommand() {
     }
 
     @Override
-    public void response(ZscriptExpression resp) {
+    public void onResponse(ZscriptExpression resp) {
     }
 
     @Override
-    public void notExecuted() {
+    public void onNotExecuted() {
     }
 }
diff --git a/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/BlankCommand.java b/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/BlankCommand.java
@@ -65,10 +65,10 @@ public byte[] compile(boolean includeParens) {
     }
 
     @Override
-    public void response(ZscriptExpression resp) {
+    public void onResponse(ZscriptExpression resp) {
     }
 
     @Override
-    public void notExecuted() {
+    public void onNotExecuted() {
     }
 }
diff --git a/...nt-command-api/src/main/java/net/zscript/javaclient/commandbuilder/CommandSeqElement.java b/...nt-command-api/src/main/java/net/zscript/javaclient/commandbuilder/CommandSeqElement.java
@@ -1,5 +1,8 @@
 package net.zscript.javaclient.commandbuilder;
 
+/**
+ * An element of a Command Sequence under construction, representing a node in the Syntax Tree of a sequence during building.
+ */
 public abstract class CommandSeqElement {
     protected CommandSeqElement parent = null;
 

diff --git a/...lient-command-api/src/main/java/net/zscript/javaclient/commandbuilder/FailureCommand.java b/...lient-command-api/src/main/java/net/zscript/javaclient/commandbuilder/FailureCommand.java
@@ -67,10 +67,10 @@ public byte[] compile(boolean includeParens) {
     }
 
     @Override
-    public void response(ZscriptExpression resp) {
+    public void onResponse(ZscriptExpression resp) {
     }
 
     @Override
-    public void notExecuted() {
+    public void onNotExecuted() {
     }
 }
diff --git a/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/OrSeqElement.java b/.../client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/OrSeqElement.java
@@ -2,6 +2,7 @@
 
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.io.UncheckedIOException;
 
 public class OrSeqElement extends CommandSeqElement {
     final CommandSeqElement before;
@@ -43,7 +44,7 @@ public byte[] compile(boolean includeParens) {
             out.write((byte) '|');
             out.write(after.compile(false));
         } catch (IOException e) {
-            throw new RuntimeException(e);
+            throw new UncheckedIOException(e);
         }
         if (includeParens) {
             out.write((byte) ')');

diff --git a/...lient-command-api/src/main/java/net/zscript/javaclient/commandbuilder/ZscriptCommand.java b/...lient-command-api/src/main/java/net/zscript/javaclient/commandbuilder/ZscriptCommand.java
@@ -4,8 +4,12 @@
 import java.util.List;
 
 import net.zscript.javareceiver.tokenizer.ZscriptExpression;
+import net.zscript.model.components.Zchars;
 
 public abstract class ZscriptCommand extends CommandSeqElement {
+    /**
+     * Represents the next command from a given point in the Syntax Tree based on the AND/OR logic of a command sequence.
+     */
     public static class ZscriptSequencePath {
         private final List<Byte>     markers;
         private final ZscriptCommand next;
@@ -30,13 +34,18 @@ public ZscriptCommand getNext() {
         }
     }
 
-    public abstract void notExecuted();
+    public abstract void onNotExecuted();
 
-    public abstract void response(ZscriptExpression resp);
+    /**
+     * Performs a command's listener callbacks when given a command's response.
+     *
+     * @param resp
+     */
+    public abstract void onResponse(ZscriptExpression resp);
 
     public static ZscriptSequencePath findFirstCommand(final CommandSeqElement start) {
         CommandSeqElement current = start;
-        CommandSeqElement prev    = null;
+        CommandSeqElement prev;
         List<Byte>        markers = new ArrayList<>();
         while (!current.isCommand()) {
             if (current.getClass() == AndSeqElement.class) {
@@ -48,8 +57,9 @@ public static ZscriptSequencePath findFirstCommand(final CommandSeqElement start
             } else {
                 throw new IllegalStateException("Unknown CommandSeqElement: " + current);
             }
+
             if (current.getClass() == OrSeqElement.class && prev.getClass() == OrSeqElement.class) {
-                markers.add((byte) '(');
+                markers.add(Zchars.Z_OPENPAREN);
             }
         }
         return new ZscriptSequencePath(markers, (ZscriptCommand) current);
@@ -64,21 +74,22 @@ public ZscriptSequencePath findNext() {
             if (current.getClass() == OrSeqElement.class) {
                 OrSeqElement orAncestor = (OrSeqElement) current;
                 if (prev == orAncestor.before) {
-                    markers.add((byte) '|');
+                    markers.add(Zchars.Z_ORELSE);
                     return new ZscriptSequencePath(markers, findFirstCommand(orAncestor.after));
                 }
             } else if (current.getClass() == AndSeqElement.class) {
                 AndSeqElement andAncestor = (AndSeqElement) current;
                 if (prev != andAncestor.getElements().get(andAncestor.getElements().size() - 1)) {
                     CommandSeqElement next = andAncestor.getElements().get(andAncestor.getElements().indexOf(prev) + 1);
                     if (prev.getClass() != OrSeqElement.class && next.getClass() != OrSeqElement.class) {
-                        markers.add((byte) '&');
+                        markers.add(Zchars.Z_ANDTHEN);
                     }
                     return new ZscriptSequencePath(markers, findFirstCommand(next));
                 }
             }
+
             if (current.getClass() == OrSeqElement.class && current.getParent() != null && current.getParent().getClass() != OrSeqElement.class) {
-                markers.add((byte) ')');
+                markers.add(Zchars.Z_CLOSEPAREN);
             }
             prev = current;
             current = current.getParent();
@@ -95,12 +106,12 @@ public ZscriptSequencePath findFailPath() {
             if (current.getClass() == OrSeqElement.class) {
                 OrSeqElement orAncestor = (OrSeqElement) current;
                 if (prev == orAncestor.before) {
-                    markers.add((byte) '|');
+                    markers.add(Zchars.Z_ORELSE);
                     return new ZscriptSequencePath(markers, findFirstCommand(orAncestor.after));
                 }
             }
             if (current.getClass() == OrSeqElement.class && current.getParent() != null && current.getParent().getClass() != OrSeqElement.class) {
-                markers.add((byte) ')');
+                markers.add(Zchars.Z_CLOSEPAREN);
             }
             prev = current;
             current = current.getParent();
@@ -119,13 +130,13 @@ public ZscriptSequencePath findSuccessPath() {
                 if (prev != andAncestor.getElements().get(andAncestor.getElements().size() - 1)) {
                     CommandSeqElement next = andAncestor.getElements().get(andAncestor.getElements().indexOf(prev) + 1);
                     if (prev.getClass() != OrSeqElement.class && next.getClass() != OrSeqElement.class) {
-                        markers.add((byte) '&');
+                        markers.add(Zchars.Z_ANDTHEN);
                     }
                     return new ZscriptSequencePath(markers, findFirstCommand(next));
                 }
             }
             if (current.getClass() == OrSeqElement.class && current.getParent() != null && current.getParent().getClass() != OrSeqElement.class) {
-                markers.add((byte) ')');
+                markers.add(Zchars.Z_CLOSEPAREN);
             }
             prev = current;
             current = current.getParent();

diff --git a/...ommand-api/src/main/java/net/zscript/javaclient/commandbuilder/ZscriptCommandBuilder.java b/...ommand-api/src/main/java/net/zscript/javaclient/commandbuilder/ZscriptCommandBuilder.java
@@ -17,6 +17,11 @@
 import net.zscript.javareceiver.tokenizer.ZscriptExpression;
 import net.zscript.model.components.Zchars;
 
+/**
+ * The builder for creating a ZscriptBuiltCommand.
+ *
+ * @param <T> the type of response this command would expect to receive
+ */
 public abstract class ZscriptCommandBuilder<T extends ZscriptResponse> {
     private static final int BIGFIELD_REQD_OFFSET = 26;
 
@@ -25,6 +30,9 @@ public abstract class ZscriptCommandBuilder<T extends ZscriptResponse> {
     private final Map<Byte, Integer>               fields         = new HashMap<>();
     private final BitSet                           requiredFields = new BitSet();
 
+    /**
+     * A representation of a command, returned by calling {@link #build()} on the builder, ready for amalgamation into a command sequence.
+     */
     public class ZscriptBuiltCommand extends ZscriptCommand {
 
         @Override
@@ -66,15 +74,15 @@ public byte[] compile(boolean includeParens) {
         }
 
         @Override
-        public void response(ZscriptExpression resp) {
+        public void onResponse(ZscriptExpression resp) {
             T parsed = parseResponse(resp);
             for (ZscriptResponseListener<T> listener : listeners) {
                 listener.accept(parsed);
             }
         }
 
         @Override
-        public void notExecuted() {
+        public void onNotExecuted() {
             for (ZscriptResponseListener<T> listener : listeners) {
                 listener.notExecuted();
             }

diff --git a/.../src/test/java/net/zscript/model/modules/testing/test/JavaCommandBuilderResponseTest.java b/.../src/test/java/net/zscript/model/modules/testing/test/JavaCommandBuilderResponseTest.java
@@ -235,7 +235,7 @@ private <R extends ZscriptResponse> void checkResponse(final String responseChar
         ZscriptCommand cmd = commandBuilder.addResponseListener(listener)
                 .build();
 
-        cmd.response(new ZscriptTokenExpression(tokenReader::iterator));
+        cmd.onResponse(new ZscriptTokenExpression(tokenReader::iterator));
     }
 
 }