tools: parse documentation metadata

doc/api_assets/style.css

@@ -106,6 +106,19 @@ code a:hover {
   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 @@
-var processIncludes = require('./preprocess.js');
-var marked = require('marked');
-var fs = require('fs');
-var path = require('path');
+'use strict';
+
+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,12 +1,15 @@
-var fs = require('fs');
-var marked = require('marked');
-var path = require('path');
-var preprocess = require('./preprocess.js');
+'use strict';
+
+const common = require('./common.js');
+const fs = require('fs');
+const marked = require('marked');
+const path = require('path');
+const preprocess = require('./preprocess.js');
 
 module.exports = toHTML;
 
 // TODO(chrisdickinson): never stop vomitting / fix this.
-var gtocPath = path.resolve(path.join(__dirname, '..', '..', 'doc', 'api', '_toc.markdown'));
+const gtocPath = path.resolve(path.join(__dirname, '..', '..', 'doc', 'api', '_toc.markdown'));
 var gtocLoading = null;
 var gtocData = null;
 
@@ -85,7 +88,7 @@ function render(lexed, filename, template, cb) {
 
     // content has to be the last thing we do with
     // the lexed tokens, because it's destructive.
-    content = marked.parser(lexed);
+    let content = marked.parser(lexed);
     template = template.replace(/__CONTENT__/g, content);
 
     cb(null, template);
@@ -123,6 +126,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;
@@ -152,6 +158,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>';
+}
 
 function parseListItem(text) {
   var parts = text.split('`');
@@ -219,4 +237,3 @@ function getId(text) {
   }
   return text;
 }
-

tools/doc/json.js

@@ -1,9 +1,12 @@
+'use strict';
+
 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};
@@ -89,6 +92,8 @@ function doJSON(input, filename, cb) {
         current.list = current.list || [];
         current.list.push(tok);
         current.list.level = 1;
+      } else if ( type === 'html' ) {
+        current.meta = parseYAML(tok.text);
       } else {
         current.desc = current.desc || [];
         if (!Array.isArray(current.desc)) {
@@ -265,6 +270,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) {