tools,doc: enable changelogs for items

PR-URL: #11489
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>

Author: addaleax

doc/api_assets/style.css

@@ -470,6 +470,12 @@ th > *:last-child, td > *:last-child {
   margin-bottom: 0;
 }
 
+.changelog > summary {
+  margin: .5rem 0;
+  padding: .5rem 0;
+  cursor: pointer;
+}
+
 /* simpler clearfix */
 .clearfix:after {
   content: ".";

test/doctool/test-doctool-html.js

@@ -47,7 +47,15 @@ const testData = [
       '<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> ' +
+      '<div class="api_metadata">' +
+      '<details class="changelog"><summary>History</summary>' +
+      '<table><tr><th>Version</th><th>Changes</th></tr>' +
+      '<tr><td>v5.3.0, v4.2.0</td>' +
+      '<td><p><span>Added in: v5.3.0, v4.2.0</span></p>' +
+      '</td></tr>' +
+      '<tr><td>v4.2.0</td><td><p>The <code>error</code> parameter can now be' +
+      'an arrow function.</p></td></tr></table></details>' +
+      '</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>' +

test/doctool/test-doctool-json.js

@@ -89,7 +89,8 @@ const testData = [
               textRaw: 'Foobar',
               name: 'foobar',
               meta: {
-                added: ['v1.0.0']
+                added: ['v1.0.0'],
+                changes: []
               },
               desc: '<p>Describe <code>Foobar</code> in more detail ' +
                 'here.</p>\n',
@@ -100,7 +101,14 @@ const testData = [
               textRaw: 'Foobar II',
               name: 'foobar_ii',
               meta: {
-                added: ['v5.3.0', 'v4.2.0']
+                added: ['v5.3.0', 'v4.2.0'],
+                changes: [
+                  { version: 'v4.2.0',
+                    'pr-url': 'https://github.com/nodejs/node/pull/3276',
+                    description: 'The `error` parameter can now be ' +
+                      'an arrow function.'
+                  }
+                ]
               },
               desc: '<p>Describe <code>Foobar II</code> in more detail ' +
                 'here.</p>\n',
@@ -112,7 +120,8 @@ const testData = [
               name: 'deprecated_thingy',
               meta: {
                 added: ['v1.0.0'],
-                deprecated: ['v2.0.0']
+                deprecated: ['v2.0.0'],
+                changes: []
               },
               desc: '<p>Describe <code>Deprecated thingy</code> in more ' +
                 'detail here.</p>\n',

test/fixtures/doc_with_yaml.md

@@ -12,6 +12,10 @@ Describe `Foobar` in more detail here.
 added:
   - v5.3.0
   - v4.2.0
+changes:
+  - version: v4.2.0
+    pr-url: https://github.com/nodejs/node/pull/3276
+    description: The `error` parameter can now be an arrow function.
 -->
 
 Describe `Foobar II` in more detail here.

tools/doc/common.js

@@ -34,6 +34,11 @@ function extractAndParseYAML(text) {
     meta.deprecated = arrify(deprecated);
   }
 
+  meta.changes = meta.changes || [];
+  meta.changes.forEach((entry) => {
+    entry.description = entry.description.replace(/^\^\s*/, '');
+  });
+
   return meta;
 }
 

tools/doc/html.js

@@ -269,12 +269,40 @@ function parseYAML(text) {
   const meta = common.extractAndParseYAML(text);
   const html = ['<div class="api_metadata">'];
 
+  const added = { description: '' };
+  const deprecated = { description: '' };
+
   if (meta.added) {
-    html.push(`<span>Added in: ${meta.added.join(', ')}</span>`);
+    added.version = meta.added.join(', ');
+    added.description = `<span>Added in: ${added.version}</span>`;
   }
 
   if (meta.deprecated) {
-    html.push(`<span>Deprecated since: ${meta.deprecated.join(', ')} </span>`);
+    deprecated.version = meta.deprecated.join(', ');
+    deprecated.description =
+        `<span>Deprecated since: ${deprecated.version}</span>`;
+  }
+
+  if (meta.changes.length > 0) {
+    let changes = meta.changes.slice();
+    if (added.description) changes.push(added);
+    if (deprecated.description) changes.push(deprecated);
+
+    changes = changes.sort((a, b) => versionSort(a.version, b.version));
+
+    html.push('<details class="changelog"><summary>History</summary>');
+    html.push('<table>');
+    html.push('<tr><th>Version</th><th>Changes</th></tr>');
+
+    changes.forEach((change) => {
+      html.push(`<tr><td>${change.version}</td>`);
+      html.push(`<td>${marked(change.description)}</td></tr>`);
+    });
+
+    html.push('</table>');
+    html.push('</details>');
+  } else {
+    html.push(`${added.description}${deprecated.description}`);
   }
 
   html.push('</div>');
@@ -390,3 +418,14 @@ function getId(text) {
   }
   return text;
 }
+
+const numberRe = /^(\d*)/;
+function versionSort(a, b) {
+  a = a.trim();
+  b = b.trim();
+  let i = 0;  // common prefix length
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  a = a.substr(i);
+  b = b.substr(i);
+  return +b.match(numberRe)[1] - +a.match(numberRe)[1];
+}