diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 1d3b65ebfeb0f4..6234bf6837f687 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -101,6 +101,9 @@ off a shared internal memory pool if `size` is less than or equal to half
use the shared internal memory pool.
### The `--zero-fill-buffers` command line option
+
Node.js can be started using the `--zero-fill-buffers` command line option to
force all newly allocated `Buffer` instances created using either
@@ -261,6 +264,9 @@ The Buffer class is a global type for dealing with binary data directly.
It can be constructed in a variety of ways.
### new Buffer(array)
+
Stability: 0 - Deprecated: Use [`Buffer.from(array)`][buffer_from_array]
instead.
@@ -276,6 +282,9 @@ const buf = new Buffer([0x62,0x75,0x66,0x66,0x65,0x72]);
```
### new Buffer(buffer)
+
Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`][buffer_from_buffer]
instead.
@@ -296,6 +305,9 @@ console.log(buf2.toString());
```
### new Buffer(arrayBuffer[, byteOffset [, length]])
+
Stability: 0 - Deprecated: Use
[`Buffer.from(arrayBuffer[, byteOffset [, length]])`][buffer_from_arraybuf]
@@ -331,6 +343,9 @@ console.log(buf);
```
### new Buffer(size)
+
Stability: 0 - Deprecated: Use
[`Buffer.alloc(size[, fill[, encoding]])`][buffer_alloc] instead (also
@@ -360,6 +375,9 @@ console.log(buf);
```
### new Buffer(str[, encoding])
+
Stability: 0 - Deprecated:
Use [`Buffer.from(str[, encoding])`][buffer_from_string] instead.
@@ -383,6 +401,9 @@ console.log(buf2.toString());
```
### Class Method: Buffer.alloc(size[, fill[, encoding]])
+
* `size` {Number}
* `fill` {Value} Default: `undefined`
@@ -427,6 +448,9 @@ contents will *never contain sensitive data*.
A `TypeError` will be thrown if `size` is not a number.
### Class Method: Buffer.allocUnsafe(size)
+
* `size` {Number}
@@ -469,6 +493,9 @@ difference is subtle but can be important when an application requires the
additional performance that `Buffer.allocUnsafe(size)` provides.
### Class Method: Buffer.allocUnsafeSlow(size)
+
* `size` {Number}
@@ -541,6 +568,9 @@ returns the actual byte length.
Otherwise, converts to `String` and returns the byte length of string.
### Class Method: Buffer.compare(buf1, buf2)
+
* `buf1` {Buffer}
* `buf2` {Buffer}
@@ -555,6 +585,9 @@ arr.sort(Buffer.compare);
```
### Class Method: Buffer.concat(list[, totalLength])
+
* `list` {Array} List of Buffer objects to concat
* `totalLength` {Number} Total length of the Buffers in the list
@@ -590,6 +623,9 @@ console.log(bufA.length);
```
### Class Method: Buffer.from(array)
+
* `array` {Array}
@@ -604,6 +640,9 @@ const buf = Buffer.from([0x62,0x75,0x66,0x66,0x65,0x72]);
A `TypeError` will be thrown if `array` is not an `Array`.
### Class Method: Buffer.from(arrayBuffer[, byteOffset[, length]])
+
* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a `TypedArray` or
a `new ArrayBuffer()`
@@ -644,6 +683,9 @@ console.log(buf.length);
A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer`.
### Class Method: Buffer.from(buffer)
+
* `buffer` {Buffer}
@@ -663,6 +705,9 @@ console.log(buf2.toString());
A `TypeError` will be thrown if `buffer` is not a `Buffer`.
### Class Method: Buffer.from(str[, encoding])
+
* `str` {String} String to encode.
* `encoding` {String} Encoding to use, Default: `'utf8'`
@@ -693,6 +738,9 @@ A `TypeError` will be thrown if `str` is not a string.
Returns 'true' if `obj` is a Buffer.
### Class Method: Buffer.isEncoding(encoding)
+
* `encoding` {String} The encoding string to test
* Return: {Boolean}
@@ -701,9 +749,10 @@ Returns true if the `encoding` is a valid encoding argument, or false
otherwise.
### buf[index]
-
-
-
+
The index operator `[index]` can be used to get and set the octet at position
`index` in the Buffer. The values refer to individual bytes, so the legal value
@@ -724,6 +773,9 @@ console.log(buf.toString('ascii'));
```
### buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
+
* `target` {Buffer}
* `targetStart` {Integer} The offset within `target` at which to begin
@@ -827,6 +879,9 @@ console.log(buf.toString());
```
### buf.entries()
+
* Return: {Iterator}
@@ -848,6 +903,9 @@ for (var pair of buf.entries()) {
```
### buf.equals(otherBuffer)
+
* `otherBuffer` {Buffer}
* Return: {Boolean}
@@ -867,6 +925,9 @@ console.log(buf1.equals(buf3));
```
### buf.fill(value[, offset[, end]][, encoding])
+
* `value` {String|Buffer|Number}
* `offset` {Number} Default: 0
@@ -899,6 +960,9 @@ Buffer(3).fill('\u0222');
```
### buf.indexOf(value[, byteOffset][, encoding])
+
* `value` {String|Buffer|Number}
* `byteOffset` {Number} Default: 0
@@ -936,6 +1000,9 @@ utf16Buffer.indexOf('\u03a3', -4, 'ucs2');
```
### buf.includes(value[, byteOffset][, encoding])
+
* `value` {String|Buffer|Number}
* `byteOffset` {Number} Default: 0
@@ -969,6 +1036,9 @@ buf.includes('this', 4);
```
### buf.keys()
+
* Return: {Iterator}
@@ -989,6 +1059,9 @@ for (var key of buf.keys()) {
```
### buf.lastIndexOf(value[, byteOffset][, encoding])
+
* `value` {String|Buffer|Number}
* `byteOffset` {Number} Default: `buf.length`
@@ -1195,6 +1268,9 @@ buf.readInt32LE(1);
### buf.readIntBE(offset, byteLength[, noAssert])
### buf.readIntLE(offset, byteLength[, noAssert])
+
* `offset` {Number} `0 <= offset <= buf.length - byteLength`
* `byteLength` {Number} `0 < byteLength <= 6`
@@ -1299,6 +1375,9 @@ console.log(buf.readUInt32LE(0));
### buf.readUIntBE(offset, byteLength[, noAssert])
### buf.readUIntLE(offset, byteLength[, noAssert])
+
* `offset` {Number} `0 <= offset <= buf.length - byteLength`
* `byteLength` {Number} `0 < byteLength <= 6`
@@ -1368,6 +1447,9 @@ buf.slice(-5, -2).toString();
```
### buf.swap16()
+
* Return: {Buffer}
@@ -1386,6 +1468,9 @@ console.log(buf);
```
### buf.swap32()
+
* Return: {Buffer}
@@ -1429,6 +1514,9 @@ buf.toString(undefined,0,5);
```
### buf.toJSON()
+
* Return: {Object}
@@ -1455,6 +1543,9 @@ console.log(copy.toString());
```
### buf.values()
+
* Return: {Iterator}
@@ -1657,6 +1748,9 @@ console.log(buf);
### buf.writeIntBE(value, offset, byteLength[, noAssert])
### buf.writeIntLE(value, offset, byteLength[, noAssert])
+
* `value` {Number} Bytes to be written to Buffer
* `offset` {Number} `0 <= offset <= buf.length - byteLength`
@@ -1821,6 +1915,9 @@ Note that this is a property on the `buffer` module as returned by
`require('buffer')`, not on the Buffer global or a Buffer instance.
## Class: SlowBuffer
+
Stability: 0 - Deprecated: Use
[`Buffer.allocUnsafeSlow(size)`][buffer_allocunsafeslow] instead.
@@ -1854,6 +1951,9 @@ Use of `SlowBuffer` should be used only as a last resort *after* a developer
has observed undue memory retention in their applications.
### new SlowBuffer(size)
+
Stability: 0 - Deprecated: Use
[`Buffer.allocUnsafeSlow(size)`][buffer_allocunsafeslow] instead.
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/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js
index afd89489f11ed4..1eb96751cc0adb 100644
--- a/test/doctool/test-doctool-html.js
+++ b/test/doctool/test-doctool-html.js
@@ -27,6 +27,31 @@ const testData = [
'Reference/Global_Objects/Array" class="type"><Array>' +
''
},
+ {
+ 'file': common.fixturesDir + '/doc_with_yaml.md',
+ 'html': 'Sample Markdown with YAML info' +
+ '#
' +
+ 'Foobar#
' +
+ 'Added in: v1.0.0
' +
+ 'Describe Foobar in more detail here.
' +
+ 'Foobar II#
' +
+ 'Added in: v5.3.0, v4.2.0
' +
+ 'Describe Foobar II in more detail here.
' +
+ 'Deprecated thingy#' +
+ '
' +
+ 'Added in: v1.0.0' +
+ 'Deprecated since: v2.0.0
Describe ' +
+ 'Deprecated thingy in more detail here.
' +
+ 'Something#
' +
+ ' ' +
+ 'Describe Something in more detail here. ' +
+ '
'
+ },
];
testData.forEach(function(item) {
diff --git a/test/doctool/test-doctool-json.js b/test/doctool/test-doctool-json.js
index 31e260fcb02d43..83563cb2d2cdac 100644
--- a/test/doctool/test-doctool-json.js
+++ b/test/doctool/test-doctool-json.js
@@ -64,6 +64,64 @@ var testData = [
'displayName': 'Title'
} ]
}
+ },
+ {
+ 'file': common.fixturesDir + '/doc_with_yaml.md',
+ 'json': {
+ 'source': 'foo',
+ 'modules': [
+ {
+ 'textRaw': 'Sample Markdown with YAML info',
+ 'name': 'sample_markdown_with_yaml_info',
+ 'modules': [
+ {
+ 'textRaw': 'Foobar',
+ 'name': 'foobar',
+ 'meta': {
+ 'added': ['v1.0.0']
+ },
+ 'desc': 'Describe Foobar in more detail ' +
+ 'here.\n\n
\n',
+ 'type': 'module',
+ 'displayName': 'Foobar'
+ },
+ {
+ 'textRaw': 'Foobar II',
+ 'name': 'foobar_ii',
+ 'meta': {
+ 'added': ['v5.3.0', 'v4.2.0']
+ },
+ 'desc': 'Describe Foobar II in more detail ' +
+ 'here.\n\n
\n',
+ 'type': 'module',
+ 'displayName': 'Foobar II'
+ },
+ {
+ 'textRaw': 'Deprecated thingy',
+ 'name': 'deprecated_thingy',
+ 'meta': {
+ 'added': ['v1.0.0'],
+ 'deprecated': ['v2.0.0']
+ },
+ 'desc': 'Describe Deprecated thingy in more ' +
+ 'detail here.\n\n
\n',
+ 'type': 'module',
+ 'displayName': 'Deprecated thingy'
+ },
+ {
+ 'textRaw': 'Something',
+ 'name': 'something',
+ 'desc': '\n\n' +
+ 'Describe Something in more detail here.\n
\n',
+ 'type': 'module',
+ 'displayName': 'Something'
+ }
+ ],
+ 'type': 'module',
+ 'displayName': 'Sample Markdown with YAML info'
+ }
+ ]
+ }
}
];
diff --git a/test/fixtures/doc_with_yaml.md b/test/fixtures/doc_with_yaml.md
new file mode 100644
index 00000000000000..493c2e7e4268b2
--- /dev/null
+++ b/test/fixtures/doc_with_yaml.md
@@ -0,0 +1,30 @@
+# Sample Markdown with YAML info
+
+## Foobar
+
+
+Describe `Foobar` in more detail here.
+
+## Foobar II
+
+
+Describe `Foobar II` in more detail here.
+
+## Deprecated thingy
+
+
+Describe `Deprecated thingy` in more detail here.
+
+## Something
+
+
+Describe `Something` in more detail here.
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..c2f561da806577
--- /dev/null
+++ b/tools/doc/common.js
@@ -0,0 +1,40 @@
+'use strict';
+
+const yaml = require('js-yaml');
+
+function isYAMLBlock(text) {
+ return !!text.match(/^$/, '');
+
+ // js-yaml.safeLoad() throws on error
+ const meta = yaml.safeLoad(text);
+
+ const added = meta.added || meta.Added;
+ if (added) {
+ // Since semver-minors can trickle down to previous major versions,
+ // features may have been added in multiple versions.
+ meta.added = arrify(added);
+ }
+
+ const deprecated = meta.deprecated || meta.Deprecated;
+ if (deprecated) {
+ // Treat deprecated like added for consistency.
+ meta.deprecated = arrify(deprecated);
+ }
+
+ return meta;
+}
+
+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..977e0834d48304 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,21 @@ function parseLists(input) {
return output;
}
+function parseYAML(text) {
+ const meta = common.extractAndParseYAML(text);
+ const html = [''];
+
+ if (meta.added) {
+ html.push(`Added in: ${meta.added.join(', ')}`);
+ }
+
+ if (meta.deprecated) {
+ html.push(`Deprecated since: ${meta.deprecated.join(', ')} `);
+ }
+
+ html.push('
');
+ return html.join('\n');
+}
// 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) {
diff --git a/tools/doc/node_modules/js-yaml/index.js b/tools/doc/node_modules/js-yaml/index.js
new file mode 100644
index 00000000000000..620bc293ffe032
--- /dev/null
+++ b/tools/doc/node_modules/js-yaml/index.js
@@ -0,0 +1,15 @@
+'use strict';
+
+// Hack to load the js-yaml module from eslint.
+// No other reason than that it’s huge.
+
+const path = require('path');
+
+const realJSYaml = path.resolve(
+ __dirname, '..', '..', '..', // tools/
+ 'eslint',
+ 'node_modules',
+ 'js-yaml'
+);
+
+module.exports = require(realJSYaml);
diff --git a/tools/doc/package.json b/tools/doc/package.json
index d87c9345b33f2e..0dda4b971cf14f 100644
--- a/tools/doc/package.json
+++ b/tools/doc/package.json
@@ -7,7 +7,8 @@
"node": ">=0.6.10"
},
"dependencies": {
- "marked": "~0.1.9"
+ "marked": "~0.1.9",
+ "js-yaml": "^3.5.2"
},
"devDependencies": {},
"optionalDependencies": {},