From 015f4fda0eecf8b5014973cd558674dcb5a120cf Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Fri, 13 Nov 2015 21:40:38 -0500 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/3867 Ref: https://github.com/nodejs/node/issues/3713 Ref: https://github.com/nodejs/node/issues/6470 PR-URL: https://github.com/nodejs/node/pull/6495 Reviewed-By: Robert Jefe Lindstaedt Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api_assets/style.css | 13 +++++++++++++ tools/doc/README.md | 27 +++++++++++++++++++++++++++ tools/doc/common.js | 21 +++++++++++++++++++++ tools/doc/generate.js | 12 ++++++------ tools/doc/html.js | 26 +++++++++++++++++++++----- tools/doc/json.js | 8 +++++++- 6 files changed, 95 insertions(+), 12 deletions(-) create mode 100644 tools/doc/common.js diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index d2fe3b718f9910..01d4ad6bc5a900 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -108,6 +108,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; } diff --git a/tools/doc/README.md b/tools/doc/README.md index fd041f001e6931..22bd053ed1b058 100644 --- a/tools/doc/README.md +++ b/tools/doc/README.md @@ -6,18 +6,27 @@ Each type of heading has a description block. ## module + Stability: 3 - Stable description and examples. ### module.property + * Type description of the property. ### module.someFunction(x, y, [z=100]) + * `x` {String} the description of the string * `y` {Boolean} Should I stay or should I go? @@ -26,6 +35,9 @@ Each type of heading has a description block. A description of the function. ### Event: 'blerg' + * Argument: SomeClass object. @@ -33,10 +45,16 @@ Each type of heading has a description block. only exception. ## Class: SomeClass + description of the class. ### Class Method: SomeClass.classMethod(anArg) + * `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() + * Return: {SomeClass object | null} The next someClass in line. ### someClass.someProperty + * String The indication of what someProperty is. ### Event: 'grelb' + * `isBlerg` {Boolean} diff --git a/tools/doc/common.js b/tools/doc/common.js new file mode 100644 index 00000000000000..72bb1eb74946a0 --- /dev/null +++ b/tools/doc/common.js @@ -0,0 +1,21 @@ +'use strict'; + +const yaml = require('js-yaml'); + +function isYAMLBlock(text) { + return !!text.match(/^$/, ''); + + // js-yaml.safeLoad() throws on error + return yaml.safeLoad(text); +} + +exports.extractAndParseYAML = extractAndParseYAML; diff --git a/tools/doc/generate.js b/tools/doc/generate.js index ff14cbd5e8979b..9048b484ce4e07 100644 --- a/tools/doc/generate.js +++ b/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(/^\-\-/)) { diff --git a/tools/doc/html.js b/tools/doc/html.js index 68ccf976b6c1f8..d31125caaa05e0 100644 --- a/tools/doc/html.js +++ b/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 = '
'; + + if (meta.added || meta.Added) { + meta.added = meta.added || meta.Added; + + html += 'Added: ' + meta.added + ''; + } + + return html + '
'; +} // Syscalls which appear in the docs, but which only exist in BSD / OSX var BSD_ONLY_SYSCALLS = new Set(['lchmod']); diff --git a/tools/doc/json.js b/tools/doc/json.js index 3d08026daaabd8..84a042f4709375 100644 --- a/tools/doc/json.js +++ b/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) {