feat(markdown): add support for comments

lib/formatInfo.js

@@ -91,6 +91,15 @@ function parsedescription(str) {
   };
 }
 
+function parsecomment(str = '') {
+  const markdown = parser.parse(str);
+  return {
+    longcomment: markdown,
+    shortcomment: shorten(stringify(markdown)),
+    comment: str,
+  };
+}
+
 function getstatus(schema) {
   if (schema[keyword`deprecated`] === true) {
     return 'deprecated';
@@ -120,6 +129,7 @@ function formatmeta(schema) {
     definedin: getdefined(schema),
     restrictions: getrestrictions(schema),
     ...parsedescription(plaindescription(schema)),
+    ...parsecomment(schema[keyword`$comment`]),
   };
 }
 

lib/markdownBuilder.js

@@ -15,6 +15,7 @@ const {
 const {
   root, paragraph, text, heading, code, table,
   tableRow, tableCell, link, inlineCode, list, listItem, strong,
+  blockquote,
 } = require('mdast-builder');
 const i18n = require('es2015-i18n-tag').default;
 const ghslugger = require('github-slugger');
@@ -218,6 +219,15 @@ function build({
     },
   ];
 
+  function makecomment(schema) {
+    if (schema[keyword`$comment`]) {
+      return [
+        blockquote(schema[s.meta].longcomment),
+      ];
+    }
+    return [];
+  }
+
 
   /**
    * Generates the overall header for the schema documentation
@@ -230,6 +240,7 @@ function build({
         heading(1, text(i18n`${gentitle(schema[s.titles], schema[keyword`type`])} Schema`)),
         paragraph(code('txt', schema[s.id] + (schema[s.pointer] ? `#${schema[s.pointer]}` : ''))),
         schema[s.meta].longdescription,
+        ...makecomment(schema),
         table('left', [
           // iterate over header
           tableRow(
@@ -696,6 +707,7 @@ function build({
         return [
           heading(level + 1, text(name)),
           description,
+          ...makecomment(definition),
           paragraph(inlineCode(name)),
           makefactlist(name, definition, required),
           ...maketypesection(definition, level + 1),
@@ -711,6 +723,7 @@ function build({
         return [
           heading(level + 1, [text(i18n`Pattern: `), inlineCode(name)]),
           description,
+          ...makecomment(definition),
           paragraph(inlineCode(name)),
           makefactlist(name, definition, required),
           ...maketypesection(definition, level + 1),
@@ -727,6 +740,7 @@ function build({
             heading(level + 1, text(i18n`Additional Properties`)),
             paragraph(text(i18n`Additional properties are allowed, as long as they follow this schema:`)),
             description,
+            ...makecomment(definition),
             makefactlist(i18n`Additional properties`, definition, required),
             ...maketypesection(definition, level + 1),
             ...makeconstraintssection(definition, level + 1),

schemasupport.md

@@ -1,15 +1,15 @@
 # JSON Schema Spec Coverage Report
 
-This report lists the keywords of the JSON Schema spec that are covered in the tests. The overall coverage is 78%
+This report lists the keywords of the JSON Schema spec that are covered in the tests. The overall coverage is 80%
 
 ## The JSON Schema Core Vocabulary
 
-Coverage for [The JSON Schema Core Vocabulary](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8.1) is 11%.
+Coverage for [The JSON Schema Core Vocabulary](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8.1) is 22%.
 
 | Keyword            | Supported |
 | :----------------- | --------- |
 | `$anchor`          | No        |
-| `$comment`         | No        |
+| `$comment`         | Yes       |
 | `$defs`            | No        |
 | `$id`              | Yes       |
 | `$recursiveAnchor` | No        |

test/fixtures/readme-1/simple.schema.json

@@ -8,6 +8,7 @@
     "$schema": "http://json-schema.org/draft-06/schema#",
     "$id": "https://example.com/schemas/simple",
     "title": "Simple",
+    "$comment": "I'm just a simple schema, living a simple life.",
     "deprecated": true,
     "writeOnly": true,
     "description": "This is a *very* simple example of a JSON schema. There is only one property.",
@@ -22,7 +23,8 @@
       },
       "name": {
           "type": "string",
-          "default": "Simply Untitled"
+          "default": "Simply Untitled",
+          "$comment": "This should be here"
       }
   }
 }

test/markdownBuilder.test.js

@@ -287,6 +287,8 @@ Reference this group by using
       .contains('Deprecated')
       .contains('"Simply Untitled"')
       .contains('Write only')
+      .contains('> This should be here')
+      .contains('living a simple life')
       .contains('# Simple Schema');
   });
 });