From 6883b2192b2e7d4f878bb9632a53de2d642b54ce Mon Sep 17 00:00:00 2001 From: susanw1 Date: Sat, 5 Oct 2024 12:50:56 +0100 Subject: [PATCH] [#167] Javadoc fixes/improvements --- .../net/zscript/javaclient/commandbuilder/Utils.java | 4 ++-- .../templates/commands/JavaCommandBuilder.mustache | 12 ++++++++++-- .../templates/commands/requestField.mustache | 12 ++++++------ .../zscript/tokenizer/AbstractArrayTokenBuffer.java | 6 +++--- .../main/java/net/zscript/tokenizer/TokenBuffer.java | 4 ++-- 5 files changed, 23 insertions(+), 15 deletions(-) diff --git a/clients/java-client-lib/client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/Utils.java b/clients/java-client-lib/client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/Utils.java index f4c412ce..f63fa9fd 100644 --- a/clients/java-client-lib/client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/Utils.java +++ b/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< + * Note: There are NO COMMANDS 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}} + *

+ * Note: There are NO NOTIFICATIONS defined in this module, which is why this enum appears empty. + {{/notifications}} */ public static enum {{#upperCamel}}{{{moduleName}}}{{/upperCamel}}Notifications { {{#notifications}} diff --git a/clients/java-client-lib/client-command-builders/src/main/resources/templates/commands/requestField.mustache b/clients/java-client-lib/client-command-builders/src/main/resources/templates/commands/requestField.mustache index 3a4ac80e..274d2a6e 100644 --- a/clients/java-client-lib/client-command-builders/src/main/resources/templates/commands/requestField.mustache +++ b/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) { diff --git a/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/AbstractArrayTokenBuffer.java b/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/AbstractArrayTokenBuffer.java index 6969854a..cc3ae9c6 100644 --- a/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/AbstractArrayTokenBuffer.java +++ b/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: *

    - *
  1. There is a writable area, owned by a TokenWriter, in the space writeStart <= i < readStart.
    2. - *
  2. There is a readable area, owned by a TokenIterator, in the space readStart <= i < writeStart.
    3. - *
  3. A token is written as >=2 bytes at writeStart: key | datalen | [data] - so tokens can be iterated by adding (datalen+2) to an existing token start.
    4. + *
  4. There is a writable area, owned by a TokenWriter, in the space writeStart <= i < readStart.
    5. + *
  5. There is a readable area, owned by a TokenIterator, in the space readStart <= i < writeStart.
    6. + *
  6. A token is written as >=2 bytes at writeStart: key | datalen | [data] - so tokens can be iterated by adding (datalen+2) to an existing token start.
    7. *
  7. A marker is written as 1 byte at writeStart, indicating a dataless key - markers are identified as a key with top 3 bits set (eg from 0xe0-0xff).
    8. *
  8. Tokens may exceed datalen of 255 using additional new token with special key TOKEN_EXTENSION
    9. *
diff --git a/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/TokenBuffer.java b/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/TokenBuffer.java index e570a1a2..291c7c82 100644 --- a/receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/TokenBuffer.java +++ b/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<->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<->reader control flags. * * @return the buffer's flags */