resolve-additional-types: improve documentation

layouts/partials/json-schema/resolve-additional-types.html

@@ -1,24 +1,48 @@
-/*
-  Finds and returns all objects, including nested ones, given a dict containing:
-   * `schema`: a JSON schema object
-   * `anchor_base`: a prefix to add to the HTML anchors generated for each object. If nil, no anchors are generated.
-   * `name`: optionally, a name to use for this object in error/warning messages. If left unset,
-      the object's `title` property is used (if present).
-
-  This template finds all nested objects inside `schema`.
-
-  Assumes that "resolve-refs" and "resolve-allof" has already been called on the
-  input schema.
-
-  Returns an array of all the objects found. The first object keeps all its properties. For all other objects, the following properties are returned:
-    * title
-    * properties
-    * required
-    * enum
-    * anchor: a string suitable for using as an html anchor for this object (if `anchor_base` was set, and the object has a title)
-
-  Note that the returned array contains only unique objects.
-*/
+/* Finds and returns all schema definitions for objects, including subschemas,
+ * in a JSON schema.
+ *
+ * The input should be a dict containing:
+ *
+ *   * `schema`: a dict containing a JSON schema.
+ *   * `anchor_base`: a prefix to add to the HTML anchors generated for each
+ *     object. If nil, no anchors are generated.
+ *   * `name`: optionally, a name to use for this schema in error/warning
+ *     messages. If left unset, the schema's `title` property is used (if
+ *     present).
+ *
+ * Assumes that "resolve-refs" and "resolve-allof" has already been called on
+ * the input schema.
+ *
+ * Returns an array of all the JSON schema definitions with `type: object` found
+ * by recursing through `schema` and inspecting any subschemas, and including
+ * `schema` itself.
+ *
+ * The returned entries are based on the JSON schema definitions found by
+ * recursing through the input `schema`, with the following differences:
+ *
+ *   * `allOf` references are expanded. (Although this partial requires that
+ *     `resolve-allof` is called on the top-level `schema` beforehand,
+ *     `resolve-allof` doesn't recurse down to subschemas).
+ *
+ *   * If `anchor_base` is set, each object with a `title` is given an `anchor`,
+ *     which is a string suitable for using as an html anchor for that object schema.
+ *
+ *   * With the *exception* of the top-level `schema` (if it is an object),
+ *     properties outside the following list are removed:
+ *
+ *     * title
+ *     * properties
+ *     * required
+ *     * enum
+ *     * anchor
+ *
+ *     In particular, this means that examples are removed (typically examples
+ *     are not helpful for subschemas), which means that duplicate schemas can
+ *     be successfully eliminated.
+ *
+ * The returned array contains only unique objects (ie, if the same object is
+ * referenced twice within `schema`, it will only be returned once).
+ */
 
 {{ $this_object := .schema }}
 {{ $anchor_base := .anchor_base }}
@@ -92,10 +116,9 @@
     {{ end }}
 {{ end }}
 
-/*
-  Handle object schemas using the `oneOf` keyword
-  (https://json-schema.org/understanding-json-schema/reference/combining.html#oneof)
-*/
+/* Handle object schemas using the `oneOf` keyword
+ * (https://json-schema.org/understanding-json-schema/reference/combining.html#oneof)
+ */
 {{ if $this_object.oneOf }}
     {{ range $idx, $item := $this_object.oneOf }}
         {{ $all_objects = partial "get-additional-objects" (dict
@@ -110,9 +133,17 @@
 {{ return uniq $all_objects }}
 
 
-/*
-  This actually makes the recursive call and adds the returned objects to the array
-*/
+/* This actually makes the recursive call and adds the returned object schema definitions to the array.
+ *
+ * Input is a dict containing:
+ *   * `this_object`: a JSON schema object.
+ *   * `name`: a name to use for this object in error/warning messages.
+ *   * `anchor_base`: a prefix to add to the HTML anchors generated for each
+ *     object. If nil, no anchors are generated.
+ *   * `all_objects`: the array of object schema definitions so far.
+ *
+ * Returns the array of object definitions.
+ */
 {{ define "partials/get-additional-objects" }}
     /* .name is the name of the object for logging purposes */
     {{ $name := .name }}
@@ -123,8 +154,8 @@
       {{ errorf "Invalid call to partials/get-additional-objects: %s is not a map" $name .this_object }}
     {{ end }}
 
-    /* although we expect resolve-allof to be called on the input, resolve-allof does not recurse into
-     * nested objects, so we have to call it again.
+    /* Although we expect resolve-allof to be called on the input, resolve-allof does not recurse into
+     * nested schemas, so we have to call it again.
      */
     {{ $this_object := partial "json-schema/resolve-allof" .this_object }}
 
@@ -135,11 +166,10 @@
     {{ return $all_objects }}
 {{ end }}
 
-/*
-  Only copy the bits of the object that we actually care about.
-  This is needed for uniqify to work - otherwise objects that are the same
-  but with (for example) different examples will be considered different.
-*/
+/* Only copy the bits of the object that we actually care about.
+ * This is needed for uniqify to work - otherwise objects that are the same
+ * but with (for example) different examples will be considered different.
+ */
 {{ define "partials/clean-object" }}
     {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }}
 {{ end }}