diff options
author | Tristian Flanagan <tflanagan@datacollaborative.com> | 2015-11-13 21:40:38 -0500 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2016-05-05 01:15:10 +0200 |
commit | 015f4fda0eecf8b5014973cd558674dcb5a120cf (patch) | |
tree | 377ef715adea2d1a28a95cfb0fcdcd3ba65f545c /tools | |
parent | 020968dd1803220b76b8fdcbf2bab54c66b695f4 (diff) | |
download | android-node-v8-015f4fda0eecf8b5014973cd558674dcb5a120cf.tar.gz android-node-v8-015f4fda0eecf8b5014973cd558674dcb5a120cf.tar.bz2 android-node-v8-015f4fda0eecf8b5014973cd558674dcb5a120cf.zip |
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 <robert.lindstaedt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Diffstat (limited to 'tools')
-rw-r--r-- | tools/doc/README.md | 27 | ||||
-rw-r--r-- | tools/doc/common.js | 21 | ||||
-rw-r--r-- | tools/doc/generate.js | 12 | ||||
-rw-r--r-- | tools/doc/html.js | 26 | ||||
-rw-r--r-- | tools/doc/json.js | 8 |
5 files changed, 82 insertions, 12 deletions
diff --git a/tools/doc/README.md b/tools/doc/README.md index fd041f001e..22bd053ed1 100644 --- a/tools/doc/README.md +++ b/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,6 +35,9 @@ Each type of heading has a description block. A description of the function. ### Event: 'blerg' + <!-- YAML + added: v0.10.0 + --> * Argument: SomeClass object. @@ -33,10 +45,16 @@ Each type of heading has a description block. 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} diff --git a/tools/doc/common.js b/tools/doc/common.js new file mode 100644 index 0000000000..72bb1eb749 --- /dev/null +++ b/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; diff --git a/tools/doc/generate.js b/tools/doc/generate.js index ff14cbd5e8..9048b484ce 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 68ccf976b6..d31125caaa 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 = '<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']); diff --git a/tools/doc/json.js b/tools/doc/json.js index 3d08026daa..84a042f470 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) { |