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 <robert.lindstaedt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

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;
 
+functionarrify(value){
+returnArray.isArray(value) ? value : [value];
+}
+
 functionextractAndParseYAML(text){
 text=text.trim();
 
 text=text.replace(/^<!--YAML/,'')
 .replace(/-->$/,'');
 
 // js-yaml.safeLoad() throws on error
-returnyaml.safeLoad(text);
+constmeta=yaml.safeLoad(text);
+
+constadded=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);
+}
+
+constdeprecated=meta.deprecated||meta.Deprecated;
+if(deprecated){
+// Treat deprecated like added for consistency.
+meta.deprecated=arrify(deprecated);
+}
+
+returnmeta;
 }
 
 exports.extractAndParseYAML=extractAndParseYAML;

tools/doc/html.js

@@ -180,15 +180,18 @@ function parseLists(input) {
 
 functionparseYAML(text){
 constmeta=common.extractAndParseYAML(text);
-lethtml='<div class="api_metadata">';
+consthtml=['<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>`);
 }
 
-returnhtml+'</div>';
+html.push('</div>');
+returnhtml.join('\n');
 }
 
 // Syscalls which appear in the docs, but which only exist in BSD / OSX