Browse Source

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>
process-exit-stdio-flushing
Tristian Flanagan 9 years ago
committed by Anna Henningsen
parent
commit
015f4fda0e
No known key found for this signature in database GPG Key ID: D8B9F5AEAE84E4CF
  1. 13
      doc/api_assets/style.css
  2. 27
      tools/doc/README.md
  3. 21
      tools/doc/common.js
  4. 12
      tools/doc/generate.js
  5. 26
      tools/doc/html.js
  6. 8
      tools/doc/json.js

13
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;
}

27
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}

21
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;

12
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(/^\-\-/)) {

26
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']);

8
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) {

Loading…
Cancel
Save