Merge branch 'bug/$comment-base64' of github.com:DavidBiesack/openapi…

…-down-convert into bug/$comment-base64

README.md

@@ -342,8 +342,6 @@ becomes
         ...
 ```
 
-### ⤓ Remove schema `$id` and `$schema`
-
 The tool removes any `$id` or `$schema` keywords that may appear
 inside schema objects.
 
@@ -358,12 +356,39 @@ However, other tools which do not allow `$comment` may not not support
 `x-comment` either.
 
 Use the `--convert-schema-comments` CLI option or set
-`convertSchemaComments`
-to `true`
-in the `Converter` constructor
+`convertSchemaComments` to `true`
+in the `Converter` constructor options
 to requst conversion of
 `$comment` to `x-comment` rather than deleting `$comment`.
 
+For example,
+
+```yaml
+    Problems:
+      title: Problems
+      description: Problem Items
+      type: array
+      maxItems: 1000
+      $comment: >-
+        The value 1000 here must match `maxItems` in the ProblemList schema.
+      items:
+         $ref: '#/components/schemas/apiProblem'
+```
+
+becomes
+
+```yaml
+    Problems:
+      title: Problems
+      description: Problem Items
+      type: array
+      maxItems: 1000
+      x-comment: >-
+        The value 1000 here must match `maxItems` in the ProblemList schema.
+      items:
+         $ref: '#/components/schemas/apiProblem'
+```
+
 ### Convert `contentEncoding: base64` to `format: byte`
 
 JSON Schema Draft 7 and later uses `contentEncoding` to specify