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');
  });
 });