Reformat docs; minor fixes

xtclang · Nov 12, 2024 · 9314931 · 9314931
1 parent 5a84542
commit 9314931
Show file tree

Hide file tree

Showing 7 changed files with 133 additions and 134 deletions.
diff --git a/lib_json/src/main/x/json/JsonArrayBuilder.x b/lib_json/src/main/x/json/JsonArrayBuilder.x
@@ -12,13 +12,13 @@ class JsonArrayBuilder
     /**
      * Create a JSON array builder.
      *
-     * @param template  an optional `JsonArray` to use to populate
-     *                  the builder with an initial set of values
-     * @param factory   a factory to create a new mutable `JsonArray`
+     * @param template  (optional) an optional `JsonArray` to use to populate the builder with an
+     *                  initial set of values
+     * @param factory   (optional) a factory to create a new mutable `JsonArray`
      */
     construct(JsonArray? template = Null, Factory factory = () -> json.newArray()) {
         this.factory = factory;
-        values = new Array();
+        this.values  = new Array();
         if (template.is(JsonArray)) {
             values.addAll(template);
         }
@@ -136,8 +136,8 @@ class JsonArrayBuilder
     /**
      * Merge a `JsonObject` into the array.
      *
-     * All of the `JsonObject` keys must be strings that are integer literals
-     * in the range between zero and the current size of the array being built.
+     * All of the `JsonObject` keys must be strings that are integer literals in the range between
+     * zero and the current size of the array being built.
      */
     @Override
     protected void mergeObject(JsonObject o) {
@@ -147,8 +147,8 @@ class JsonArrayBuilder
             Int?        index   = pointer.index;
             assert index != Null as "Cannot merge JSON Object with non-Int keys into a JSON array";
             assert 0 <= index < values.size as
-                    $|Cannot merge JSON Object into JSON array - key\
-                     | "{entry.key}" does not match an existing array entry in the range 0..<{values.size}
+                    $|Cannot merge JSON Object into JSON array - key "{entry.key}" does not match \
+                     |an existing array entry in the range 0..<{values.size}
                      ;
             map.put(pointer, entry.value);
         }

diff --git a/lib_json/src/main/x/json/JsonBuilder.x b/lib_json/src/main/x/json/JsonBuilder.x
@@ -22,11 +22,10 @@ class JsonBuilder<JsonType extends JsonStruct, Id extends Int | String> {
     @Abstract protected Id id(JsonPointer path);
 
     /**
-     * Merge the specified `Doc` into the entry in this builder
-     * with the specified `Id`.
+     * Merge the specified `Doc` into the entry in this builder with the specified `Id`.
      *
-     * The exact behaviour and merge rules will differ depending on the
-     * type of JSON value the builder builds.
+     * The exact behaviour and merge rules will differ depending on the type of JSON value the
+     * builder builds.
      */
     @Abstract protected void merge(Id id, Doc doc);
 
@@ -41,30 +40,29 @@ class JsonBuilder<JsonType extends JsonStruct, Id extends Int | String> {
     /**
      * Return the `Doc` value the builder contains for the specified `Id`.
      *
-     * As a `Doc` type can be `Null`, if there is no entry contained in the
-     * builder for the specified `Id` then a `Null` value will be returned,
-     * which is a valid `Doc` value.
+     * As a `Doc` type can be `Null`, if there is no entry contained in the builder for the
+     * specified `Id` then a `Null` value will be returned,  which is a valid `Doc` value.
      */
     @Abstract protected Doc get(Id id);
 
     /**
-     * Perform a deep merge of the specified JSON structure with
-     * the JSON structure this builder is building.
+     * Perform a deep merge of the specified JSON structure with the JSON structure this builder is
+     * building.
      *
-     * How the merge is performed will differ depending on the type of
-     * structure passed in and the structure being built.
+     * How the merge is performed will differ depending on the type of structure passed in and the
+     * structure being built.
      *
-     * @param  the `JsonStruct` to merge
+     * @param jsonStruct the `JsonStruct` to merge
      *
      * @return this `JsonBuilder`
      */
-    JsonBuilder deepMerge(JsonStruct s) {
-        switch (s.is(_)) {
+    JsonBuilder deepMerge(JsonStruct jsonStruct) {
+        switch (jsonStruct.is(_)) {
         case JsonObject:
-            mergeObject(s);
+            mergeObject(jsonStruct);
             break;
         case JsonArray:
-            mergeArray(s);
+            mergeArray(jsonStruct);
             break;
         default:
             assert;
@@ -104,66 +102,65 @@ class JsonBuilder<JsonType extends JsonStruct, Id extends Int | String> {
     }
 
     /**
-     * Deeply merge the entries in a `JsonObject` into the JSON value being
-     * produced by this builder.
+     * Deeply merge the entries in a `JsonObject` into the JSON value being produced by this builder.
      *
-     * @param o  the `JsonObject` to merge
+     * @param jsonObj  the `JsonObject` to merge
      */
-    protected void mergeObject(JsonObject o) {
-        for (Map.Entry<String, Doc> entry : o.entries) {
+    protected void mergeObject(JsonObject jsonObj) {
+        for (Map.Entry<String, Doc> entry : jsonObj.entries) {
             deepMerge(JsonPointer.from(entry.key), entry.value);
         }
     }
 
     /**
      * Deeply merge a `JsonObject` value into this builder.
      *
-     * @param p     the `JsonObject` to merge
+     * @param obj   the `JsonObject` to merge
      * @param path  the path to the location the object value should be merged into
      * @param doc   the value to merge the object into
      * @param id    the id of the entry being merged into
      */
-    protected void mergeObjectMember(JsonObject o, JsonPointer path, Doc doc, Id id) {
+    protected void mergeObjectMember(JsonObject obj, JsonPointer path, Doc doc, Id id) {
         JsonPointer remainder = path.remainder ?: assert;
-        JsonObject  updated   = new JsonObjectBuilder(o).deepMerge(remainder, doc).build();
+        JsonObject  updated   = new JsonObjectBuilder(obj).deepMerge(remainder, doc).build();
         update(id, updated);
     }
 
     /**
      * Deeply merge the entries in a `JsonArray` into the JSON value being
      * produced by this builder.
      *
-     * @param a  the `JsonArray` to merge
+     * @param array  the `JsonArray` to merge
      */
-    protected void mergeArray(JsonArray a) {
-        for (Int i : 0 ..< a.size) {
-            deepMerge(JsonPointer.from(i.toString()), a[i]);
+    protected void mergeArray(JsonArray array) {
+        for (Int i : 0 ..< array.size) {
+            deepMerge(JsonPointer.from(i.toString()), array[i]);
         }
     }
 
     /**
      * Deeply merge a `JsonArray` value into this builder.
      *
-     * @param a     the `JsonArray` to merge
-     * @param path  the path to the location the array value should be merged into
-     * @param doc   the value to merge the array into
-     * @param id    the id of the entry being merged into
+     * @param array  the `JsonArray` to merge
+     * @param path   the path to the location the array value should be merged into
+     * @param doc    the value to merge the array into
+     * @param id     the id of the entry being merged into
      */
-    protected void mergeArrayMember(JsonArray a, JsonPointer path, Doc doc, Id id) {
+    protected void mergeArrayMember(JsonArray array, JsonPointer path, Doc doc, Id id) {
         JsonPointer remainder = path.remainder ?: assert;
-        JsonArray   updated   = new JsonArrayBuilder(a).deepMerge(remainder, doc).build();
+        JsonArray   updated   = new JsonArrayBuilder(array).deepMerge(remainder, doc).build();
         update(id, updated);
     }
 
     /**
-     * Deeply merge a `Primitive` value into this builder.
+     * Deeply merge a `Primitive` json value into this builder.
      *
-     * @param p     the `Primitive` to merge
+     * @param obj   the `Primitive` value to merge (TODO JK: value is not used!?)
      * @param path  the path to the location the primitive value should be merged into
      * @param doc   the value to merge the primitive into
      * @param id    the id of the entry being merged into
      */
-    protected void mergePrimitiveMember(Primitive p, JsonPointer path, Doc doc, Id id) {
+    protected void mergePrimitiveMember(Primitive obj, JsonPointer path, Doc doc, Id id) {
         JsonPointer remainder = path.remainder ?: assert;
         JsonObject  updated   = new JsonObjectBuilder().deepMerge(remainder, doc).build();
         update(id, updated);
@@ -205,13 +202,13 @@ class JsonBuilder<JsonType extends JsonStruct, Id extends Int | String> {
     /**
      * Perform a deep copy of the specified JSON array.
      *
-     * @param o  the JSON array to copy
+     * @param array  the JSON array to copy
      *
      * @return a mutable copy of the JSON array
      */
-    static JsonArray deepCopyArray(JsonArray a) {
+    static JsonArray deepCopyArray(JsonArray array) {
         JsonArray copy = json.newArray();
-        for (Doc doc : a) {
+        for (Doc doc : array) {
             copy.add(deepCopy(doc));
         }
         return copy;

diff --git a/lib_json/src/main/x/json/JsonMergePatch.x b/lib_json/src/main/x/json/JsonMergePatch.x
@@ -1,13 +1,13 @@
 /**
- * An implementation of a JSON Merge Patch as specified
- * in [RFC7396](http://tools.ietf.org/html/rfc7396).
+ * An implementation of a JSON Merge Patch as specified in
+ * [JSON Merge Patch specification](http://tools.ietf.org/html/rfc7396).
  *
  * @param patch  the JSON value to apply as a merge patch
  */
 class JsonMergePatch(Doc patch) {
 
     /**
-     * @return True iff this patch is empty, i.e. it will not apply any
+     * `True` iff this patch is empty, i.e. it will not apply to any.
      */
     Boolean empty.get() {
         Doc patch = this.patch;
@@ -21,9 +21,8 @@ class JsonMergePatch(Doc patch) {
      * Apply this patch to the specified target.
      *
      * @param target   the JSON value to apply this patch to
-     * @param inPlace  True to modify the target in place (if applicable), or
-     *                 False to leave the target unmodified and return a patched
-     *                 copy of the target
+     * @param inPlace  (optional) `True` to modify the target in place (if applicable), or `False`
+     *                 to leave the target unmodified and return a patched copy of the target
      *
      * @return the JSON value resulting from applying this patch to the target
      */
@@ -51,7 +50,7 @@ class JsonMergePatch(Doc patch) {
                     if (Doc targetValue := target.get(key)) {
                         merge(key, merge(targetValue, value, inPlace));
                     } else {
-                        merge(key, merge(json.newObject(), value, True));
+                        merge(key, merge(json.newObject(), value, True)); // TODO JK: why not "inPlace"
                     }
                 }
             }
@@ -75,8 +74,8 @@ class JsonMergePatch(Doc patch) {
     /**
      * Generate a JSON Merge Patch from the source and target {@code JsonValue}.
      *
-     * @param source the source
-     * @param target the target
+     * @param source  the source
+     * @param target  the target
      *
      * @return a JSON Patch which when applied to the source, yields the target
      */

diff --git a/lib_json/src/main/x/json/JsonObjectBuilder.x b/lib_json/src/main/x/json/JsonObjectBuilder.x
@@ -12,9 +12,9 @@ class JsonObjectBuilder
     /**
      * Create a JSON object builder.
      *
-     * @param template  an optional `Map<String, Doc>` to use to populate
-     *                  the builder with an initial set of values
-     * @param factory   a factory to create a new mutable `JsonArray`
+     * @param template  (optional) an optional `Map<String, Doc>` to use to populate the builder
+     *                  with an initial set of values
+     * @param factory   (optional) a factory to create a new mutable `JsonArray`
      */
     construct(JsonObject? template = Null, Factory factory = () -> json.newObject()) {
         this.factory = factory;
@@ -63,7 +63,7 @@ class JsonObjectBuilder
     JsonObjectBuilder add(String key, JsonBuilder builder) = add(key, builder.build());
 
     /**
-     * Add all the values contained in the `Map`
+     * Add all the values contained in the `Map`.
      *
      * @param map  the map of values to add
      *
@@ -75,7 +75,7 @@ class JsonObjectBuilder
     }
 
     /**
-     * Add all the values contained in the `JsonObject`
+     * Add all the values contained in the `JsonObject`.
      *
      * @param map  the map of values to add
      *