[#167] Javadoc fixes/improvements

clients/java-client-lib/client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/Utils.java

@@ -16,8 +16,8 @@
  */
 public class Utils {
     /**
-     * Converts a number representing an OR'ed set of bits into the corresponding values in an Enum, returned as an EnumSet. Bit 0 is the first value in the Enum, bit n is the 1<<n
-     * value etc.
+     * Converts a number representing an OR'ed set of bits into the corresponding values in an Enum, returned as an EnumSet. Bit 0 is the first value in the Enum, bit n is the
+     * 1&lt;&lt;n  value etc.
      *
      * @param bitFields an int representing a set of bits
      * @param enumClass the enum type to match

clients/java-client-lib/client-command-builders/src/main/resources/templates/commands/JavaCommandBuilder.mustache

@@ -44,7 +44,11 @@ public final class {{#upperCamel}}{{{moduleName}}}{{/upperCamel}}Module {
 
     {{! ============ COMMAND SUMMARY ENUM ============= }}
     /**
-     * Defines constants for the commands defined in the '{{#upperCamel}}{{{moduleName}}}{{/upperCamel}}' module. Each command has a CMD field referencing its constant.
+     * Defines constants for the commands defined in the '{{#upperCamel}}{{{moduleName}}}{{/upperCamel}}' module. Each command has a CMD field referencing its enum constant.
+    {{^commands}}
+    * <p>
+    * Note: There are <b>NO COMMANDS</b> defined in this module, which is why this enum appears empty.
+    {{/commands}}
      */
     public static enum {{#upperCamel}}{{{moduleName}}}{{/upperCamel}}Commands {
 {{#commands}}
@@ -75,7 +79,11 @@ public final class {{#upperCamel}}{{{moduleName}}}{{/upperCamel}}Module {
     {{! ============ NOTIFICATION SUMMARY ENUM ============= }}
 
     /**
-     * Defines the set of all notifications defined in the '{{#upperCamel}}{{{moduleName}}}{{/upperCamel}}' module.
+     * Defines the set of all notifications defined in the '{{#upperCamel}}{{{moduleName}}}{{/upperCamel}}' module. Each NotificationId has a NTFN field referencing its constant.
+    {{^notifications}}
+    * <p>
+    * Note: There are <b>NO NOTIFICATIONS</b> defined in this module, which is why this enum appears empty.
+    {{/notifications}}
      */
     public static enum {{#upperCamel}}{{{moduleName}}}{{/upperCamel}}Notifications {
 {{#notifications}}

clients/java-client-lib/client-command-builders/src/main/resources/templates/commands/requestField.mustache

@@ -257,7 +257,7 @@
              * {{longDescription}}
             {{/longDescription}}
              *
-             * @param value  the bit in the {{#lowerCamel}}{{{fieldName}}}{{/lowerCamel}} to set, as an Optional enum  (if empty, then no change is made)
+             * @param bit    the bit in the {{#lowerCamel}}{{{fieldName}}}{{/lowerCamel}} to set, as an Optional enum  (if empty, then no change is made)
              * @return this builder, to facilitate method chaining
              */
             public Builder set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}(@Nonnull final Optional<{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}> bit) {
@@ -274,11 +274,11 @@
             {{/longDescription}}
              *
              * @param condition if true, then set the field; otherwise, no change is made
-             * @param value     the {{#lowerCamel}}{{{fieldName}}}{{/lowerCamel}} to set
+             * @param bit       the {{#lowerCamel}}{{{fieldName}}}{{/lowerCamel}} to set
              * @return this builder, to facilitate method chaining
              */
-            public Builder set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}If(final boolean condition, @Nonnull final {{#upperCamel}}{{{fieldName}}}{{/upperCamel}} value) {
-                return condition ? set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}(value) : this;
+            public Builder set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}If(final boolean condition, @Nonnull final {{#upperCamel}}{{{fieldName}}}{{/upperCamel}} bit) {
+                return condition ? set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}(bit) : this;
             }
             {{/required}}
                         {{/bitsetType}}
@@ -310,7 +310,7 @@
              * {{longDescription}}
             {{/longDescription}}
              *
-             * @param text      the bytes to add to the big-field
+             * @param bytes     the bytes to add to the big-field
              * @return this builder, to facilitate method chaining
              */
             public Builder set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}AsBytes(@Nonnull final byte[] bytes) {
@@ -327,7 +327,7 @@
              * {{longDescription}}
             {{/longDescription}}
              *
-             * @param text      the bytes to add to the big-field
+             * @param bytes     the bytes to add to the big-field
              * @return this builder, to facilitate method chaining
              */
             public Builder set{{#upperCamel}}{{{fieldName}}}{{/upperCamel}}AsSmallest(@Nonnull final byte[] bytes) {

receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/AbstractArrayTokenBuffer.java

@@ -14,9 +14,9 @@
 /**
  * Array based implementation of a TokenBuffer - the tokens making up incoming command or response sequences are encoded and accessed here. Rules are:
  * <ol>
- * <li>There is a writable area, owned by a TokenWriter, in the space <i>writeStart <= i < readStart</i>.</li>
- * <li>There is a readable area, owned by a TokenIterator, in the space <i>readStart <= i < writeStart</i>.</li>
- * <li>A token is written as >=2 bytes at <i>writeStart</i>: <code>key | datalen | [data]</code> - so tokens can be iterated by adding (datalen+2) to an existing token start.</li>
+ * <li>There is a writable area, owned by a TokenWriter, in the space <i>writeStart &lt;= i &lt; readStart</i>.</li>
+ * <li>There is a readable area, owned by a TokenIterator, in the space <i>readStart &lt;= i &lt; writeStart</i>.</li>
+ * <li>A token is written as &gt;=2 bytes at <i>writeStart</i>: <code>key | datalen | [data]</code> - so tokens can be iterated by adding (datalen+2) to an existing token start.</li>
  * <li>A marker is written as 1 byte at <i>writeStart</i>, indicating a dataless key - markers are identified as a key with top 3 bits set (eg from 0xe0-0xff).</li>
  * <li>Tokens may exceed datalen of 255 using additional new token with special key <i>TOKEN_EXTENSION</i></li>
  * </ol>

receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/TokenBuffer.java

@@ -45,7 +45,7 @@ static boolean isSequenceEndMarker(byte key) {
      */
     interface TokenWriter {
         /**
-         * Access the writer<->reader control flags.
+         * Access the writer&lt;-&gt;reader control flags.
          *
          * @return the buffer's flags
          */
@@ -154,7 +154,7 @@ interface TokenWriter {
      */
     interface TokenReader {
         /**
-         * Access the writer<->reader control flags.
+         * Access the writer&lt;-&gt;reader control flags.
          *
          * @return the buffer's flags
          */