tools: parse documentation metadata

This commit introduces the Documentation YAML metadata concept to the
documentation.

- Parses added or Added for HTML
- Parses all data for JSON

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

doc/api_assets/style.css

@@ -103,6 +103,19 @@ em code {
   background-color: #0084B6;
 }
 
+.api_metadata {
+  font-size: .75em;
+  margin-bottom: 1em;
+}
+
+.api_metadata span {
+  margin-right: 1em;
+}
+
+.api_metadata span:last-child {
+  margin-right: 0px;
+}
+
 ul.plain {
   list-style: none;
 }

tools/doc/README.md

@@ -6,18 +6,27 @@ Each type of heading has a description block.
 
 
     ## module
+    <!-- YAML
+    added: v0.10.0
+    -->
 
         Stability: 3 - Stable
 
     description and examples.
 
     ### module.property
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * Type
 
     description of the property.
 
     ### module.someFunction(x, y, [z=100])
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * `x` {String} the description of the string
     * `y` {Boolean} Should I stay or should I go?
@@ -26,17 +35,26 @@ Each type of heading has a description block.
     A description of the function.
 
     ### Event: 'blerg'
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * Argument: SomeClass object.
 
     Modules don't usually raise events on themselves.  `cluster` is the
     only exception.
 
     ## Class: SomeClass
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     description of the class.
 
     ### Class Method: SomeClass.classMethod(anArg)
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * `anArg` {Object}  Just an argument
       * `field` {String} anArg can have this field.
@@ -46,16 +64,25 @@ Each type of heading has a description block.
     Description of the method for humans.
 
     ### someClass.nextSibling()
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * Return: {SomeClass object | null}  The next someClass in line.
 
     ### someClass.someProperty
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * String
 
     The indication of what someProperty is.
 
     ### Event: 'grelb'
+    <!-- YAML
+    added: v0.10.0
+    -->
 
     * `isBlerg` {Boolean}
 

tools/doc/common.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const yaml = require('js-yaml');
+
+function isYAMLBlock(text) {
+  return !!text.match(/^<!-- YAML/);
+}
+
+exports.isYAMLBlock = isYAMLBlock;
+
+function extractAndParseYAML(text) {
+  text = text.trim();
+
+  text = text.replace(/^<!-- YAML/, '')
+             .replace(/-->$/, '');
+
+  // js-yaml.safeLoad() throws on error
+  return yaml.safeLoad(text);
+}
+
+exports.extractAndParseYAML = extractAndParseYAML;

tools/doc/generate.js

@@ -1,15 +1,15 @@
 'use strict';
 
-var processIncludes = require('./preprocess.js');
-var fs = require('fs');
+const processIncludes = require('./preprocess.js');
+const fs = require('fs');
 
 // parse the args.
 // Don't use nopt or whatever for this.  It's simple enough.
 
-var args = process.argv.slice(2);
-var format = 'json';
-var template = null;
-var inputFile = null;
+const args = process.argv.slice(2);
+let format = 'json';
+let template = null;
+let inputFile = null;
 
 args.forEach(function(arg) {
   if (!arg.match(/^\-\-/)) {

tools/doc/html.js

@@ -1,10 +1,11 @@
 'use strict';
 
-var fs = require('fs');
-var marked = require('marked');
-var path = require('path');
-var preprocess = require('./preprocess.js');
-var typeParser = require('./type-parser.js');
+const common = require('./common.js');
+const fs = require('fs');
+const marked = require('marked');
+const path = require('path');
+const preprocess = require('./preprocess.js');
+const typeParser = require('./type-parser.js');
 
 module.exports = toHTML;
 
@@ -148,6 +149,9 @@ function parseLists(input) {
         output.push(tok);
         return;
       }
+      if (tok.type === 'html' && common.isYAMLBlock(tok.text)) {
+        tok.text = parseYAML(tok.text);
+      }
       state = null;
       output.push(tok);
       return;
@@ -174,6 +178,18 @@ function parseLists(input) {
   return output;
 }
 
+function parseYAML(text) {
+  const meta = common.extractAndParseYAML(text);
+  let html = '<div class="api_metadata">';
+
+  if (meta.added || meta.Added) {
+    meta.added = meta.added || meta.Added;
+
+    html += '<span>Added: ' + meta.added + '</span>';
+  }
+
+  return html + '</div>';
+}
 
 // Syscalls which appear in the docs, but which only exist in BSD / OSX
 var BSD_ONLY_SYSCALLS = new Set(['lchmod']);

tools/doc/json.js

@@ -5,7 +5,8 @@ module.exports = doJSON;
 // Take the lexed input, and return a JSON-encoded object
 // A module looks like this: https://gist.github.com/1777387
 
-var marked = require('marked');
+const common = require('./common.js');
+const marked = require('marked');
 
 function doJSON(input, filename, cb) {
   var root = {source: filename};
@@ -91,6 +92,8 @@ function doJSON(input, filename, cb) {
         current.list = current.list || [];
         current.list.push(tok);
         current.list.level = 1;
+      } else if (type === 'html' && common.isYAMLBlock(tok.text)) {
+        current.meta = parseYAML(tok.text);
       } else {
         current.desc = current.desc || [];
         if (!Array.isArray(current.desc)) {
@@ -274,6 +277,9 @@ function processList(section) {
   delete section.list;
 }
 
+function parseYAML(text) {
+  return common.extractAndParseYAML(text);
+}
 
 // textRaw = "someobject.someMethod(a[, b=100][, c])"
 function parseSignature(text, sig) {