From a9f946767cfdf0aaa9d5fc163b4bfdbbc2a69f00 Mon Sep 17 00:00:00 2001
From: David Biesack <David.Biesack@apiture.com>
Date: Wed, 22 Nov 2023 12:26:15 -0500
Subject: [PATCH] Update README.md

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index af1311b..640134a 100644
--- a/README.md
+++ b/README.md
@@ -331,6 +331,40 @@ becomes
         ...
 ```
 
+### Rename `$comment` as `x-comment`
+
+The tool renames the `$comment` keyword in schema objects as `x-comment`
+as `$comment` is not supported in OAS 3.0 JSON Schema Draft 4
+used in OAS 3.0. and can cause problems with some tools.
+`x-comment` is more easily ignored since it does not start with `$`.
+
+For exmample,
+```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'
+```
+
 ### Remove schema `$id` and `$schema`
 
 The tool removes any `$id` or `$schema` keywords that may appear