tools: allow multiple added: version entries

Allow multiple `added:` version entries, since semver-minors
can trickle down to previous major versions, and thus
features may have been added in multiple versions.

Also include `deprecated:` entries and apply the same logic
to them for consistency.

Stylize the added HTML as `Added in:` and `Deprecated since:`.

PR-URL: #6495
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>

Author: addaleax

test/doctool/test-doctool-html.js

@@ -34,12 +34,17 @@ const testData = [
       ' id="foo_sample_markdown_with_yaml_info">#</a></span></h1>' +
       '<h2>Foobar<span><a class="mark" href="#foo_foobar" ' +
       'id="foo_foobar">#</a></span></h2>' +
-      '<div class="api_metadata"><span>Added: v1.0.0</span></div> ' +
+      '<div class="api_metadata"><span>Added in: v1.0.0</span></div> ' +
       '<p>Describe <code>Foobar</code> in more detail here.</p>' +
+      '<h2>Foobar II<span><a class="mark" href="#foo_foobar_ii" ' +
+      'id="foo_foobar_ii">#</a></span></h2>' +
+      '<div class="api_metadata"><span>Added in: v5.3.0, v4.2.0</span></div> ' +
+      '<p>Describe <code>Foobar II</code> in more detail here.</p>' +
       '<h2>Deprecated thingy<span><a class="mark" ' +
       'href="#foo_deprecated_thingy" id="foo_deprecated_thingy">#</a>' +
       '</span></h2>' +
-      '<div class="api_metadata"><span>Added: v1.0.0</span></div><p>Describe ' +
+      '<div class="api_metadata"><span>Added in: v1.0.0</span>' +
+      '<span>Deprecated since: v2.0.0</span></div><p>Describe ' +
       '<code>Deprecated thingy</code> in more detail here.</p>' +
       '<h2>Something<span><a class="mark" href="#foo_something" ' +
       'id="foo_something">#</a></span></h2> ' +

test/doctool/test-doctool-json.js

@@ -78,19 +78,30 @@ var testData = [
               'textRaw': 'Foobar',
               'name': 'foobar',
               'meta': {
-                'added': 'v1.0.0'
+                'added': ['v1.0.0']
               },
               'desc': '<p>Describe <code>Foobar</code> in more detail ' +
                 'here.\n\n</p>\n',
               'type': 'module',
               'displayName': 'Foobar'
             },
+            {
+              'textRaw': 'Foobar II',
+              'name': 'foobar_ii',
+              'meta': {
+                'added': ['v5.3.0', 'v4.2.0']
+              },
+              'desc': '<p>Describe <code>Foobar II</code> in more detail ' +
+                'here.\n\n</p>\n',
+              'type': 'module',
+              'displayName': 'Foobar II'
+            },
             {
               'textRaw': 'Deprecated thingy',
               'name': 'deprecated_thingy',
               'meta': {
-                'added': 'v1.0.0',
-                'deprecated': 'v2.0.0'
+                'added': ['v1.0.0'],
+                'deprecated': ['v2.0.0']
               },
               'desc': '<p>Describe <code>Deprecated thingy</code> in more ' +
                 'detail here.\n\n</p>\n',

test/fixtures/doc_with_yaml.md

@@ -7,6 +7,15 @@ added: v1.0.0
 
 Describe `Foobar` in more detail here.
 
+## Foobar II
+<!-- YAML
+added:
+  - v5.3.0
+  - v4.2.0
+-->
+
+Describe `Foobar II` in more detail here.
+
 ## Deprecated thingy
 <!-- YAML
 added: v1.0.0

tools/doc/common.js

@@ -8,14 +8,33 @@ function isYAMLBlock(text) {
 
 exports.isYAMLBlock = isYAMLBlock;
 
+function arrify(value) {
+  return Array.isArray(value) ? value : [value];
+}
+
 function extractAndParseYAML(text) {
   text = text.trim();
 
   text = text.replace(/^<!-- YAML/, '')
              .replace(/-->$/, '');
 
   // js-yaml.safeLoad() throws on error
-  return yaml.safeLoad(text);
+  const meta = yaml.safeLoad(text);
+
+  const added = meta.added || meta.Added;
+  if (added) {
+    // Since semver-minors can trickle down to previous major versions,
+    // features may have been added in multiple versions.
+    meta.added = arrify(added);
+  }
+
+  const deprecated = meta.deprecated || meta.Deprecated;
+  if (deprecated) {
+    // Treat deprecated like added for consistency.
+    meta.deprecated = arrify(deprecated);
+  }
+
+  return meta;
 }
 
 exports.extractAndParseYAML = extractAndParseYAML;

tools/doc/html.js

@@ -180,15 +180,18 @@ function parseLists(input) {
 
 function parseYAML(text) {
   const meta = common.extractAndParseYAML(text);
-  let html = '<div class="api_metadata">';
+  const html = ['<div class="api_metadata">'];
 
-  if (meta.added || meta.Added) {
-    meta.added = meta.added || meta.Added;
+  if (meta.added) {
+    html.push(`<span>Added in: ${meta.added.join(', ')}</span>`);
+  }
 
-    html += '<span>Added: ' + meta.added + '</span>';
+  if (meta.deprecated) {
+    html.push(`<span>Deprecated since: ${meta.deprecated.join(', ')} </span>`);
   }
 
-  return html + '</div>';
+  html.push('</div>');
+  return html.join('\n');
 }
 
 // Syscalls which appear in the docs, but which only exist in BSD / OSX