daohualiuxiang
/
node
mirror of https://github.com/nodejs/node.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: use blockquotes for Stability: markers 

Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (https://github.com/nodejs/node/pull/7729).

PR-URL: https://github.com/nodejs/node/pull/7757
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
pull/7854/merge
Anna Henningsen 2016-07-16 00:35:38 +02:00
parent 561958e565
commit c809b88345
No known key found for this signature in database
GPG Key ID: D8B9F5AEAE84E4CF
36 changed files with 120 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/assert.md
View File

@ -1,6 +1,6 @@
# Assert
Stability: 3 - Locked
> Stability: 3 - Locked
The `assert` module provides a simple set of assertion tests that can be used to
test invariants. The module is intended for internal use by Node.js, but can be

24
doc/api/buffer.md
View File

@ -1,6 +1,6 @@
# Buffer
Stability: 2 - Stable
> Stability: 2 - Stable
Prior to the introduction of [`TypedArray`] in ECMAScript 2015 (ES6), the
JavaScript language had no mechanism for reading or manipulating streams
@ -300,7 +300,7 @@ It can be constructed in a variety of ways.
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead.
> Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead.
* `array` {Array} An array of bytes to copy from
@ -318,7 +318,7 @@ const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.
> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.
* `buffer` {Buffer} An existing `Buffer` to copy data from
@ -344,9 +344,9 @@ console.log(buf2.toString());
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use
[`Buffer.from(arrayBuffer[, byteOffset [, length]])`][`Buffer.from(arrayBuffer)`]
instead.
> Stability: 0 - Deprecated: Use
> [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][`Buffer.from(arrayBuffer)`]
> instead.
* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a [`TypedArray`] or
[`ArrayBuffer`]
@ -387,8 +387,8 @@ console.log(buf);
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see
[`Buffer.allocUnsafe()`]).
> Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see
> [`Buffer.allocUnsafe()`]).
* `size` {Integer} The desired length of the new `Buffer`
@ -420,8 +420,8 @@ console.log(buf);
deprecated: v6.0.0
-->
Stability: 0 - Deprecated:
Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
> Stability: 0 - Deprecated:
> Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
* `string` {String} String to encode
* `encoding` {String} The encoding of `string`. **Default:** `'utf8'`
@ -2309,7 +2309,7 @@ On 64-bit architectures, this value is `(2^31)-1` (~2GB).
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead.
> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead.
Returns an un-pooled `Buffer`.
@ -2349,7 +2349,7 @@ has observed undue memory retention in their applications.
deprecated: v6.0.0
-->
Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead.
> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead.
* `size` {Integer} The desired length of the new `SlowBuffer`

2
doc/api/child_process.md
View File

@ -1,6 +1,6 @@
# Child Process
Stability: 2 - Stable
> Stability: 2 - Stable
The `child_process` module provides the ability to spawn child processes in
a manner that is similar, but not identical, to popen(3). This capability

4
doc/api/cluster.md
View File

@ -1,6 +1,6 @@
# Cluster
Stability: 2 - Stable
> Stability: 2 - Stable
A single instance of Node.js runs in a single thread. To take advantage of
multi-core systems the user will sometimes want to launch a cluster of Node.js
@ -395,7 +395,7 @@ if (cluster.isMaster) {
### worker.suicide
Stability: 0 - Deprecated: Use [`worker.exitedAfterDisconnect`][] instead.
> Stability: 0 - Deprecated: Use [`worker.exitedAfterDisconnect`][] instead.
An alias to [`worker.exitedAfterDisconnect`][].

2
doc/api/console.md
View File

@ -1,6 +1,6 @@
# Console
Stability: 2 - Stable
> Stability: 2 - Stable
The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

6
doc/api/crypto.md
View File

@ -1,6 +1,6 @@
# Crypto
Stability: 2 - Stable
> Stability: 2 - Stable
The `crypto` module provides cryptographic functionality that includes a set of
wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions.
@ -510,7 +510,7 @@ public point (key) is also generated and set in the ECDH object.
### ecdh.setPublicKey(public_key[, encoding])
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
Sets the EC Diffie-Hellman public key. Key encoding can be `'latin1'`,
`'hex'` or `'base64'`. If `encoding` is provided `public_key` is expected to
@ -918,7 +918,7 @@ The `key` is the raw key used by the `algorithm` and `iv` is an
### crypto.createCredentials(details)
Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
> Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
The `crypto.createCredentials()` method is a deprecated alias for creating
and returning a `tls.SecureContext` object. The `crypto.createCredentials()`

2
doc/api/debugger.md
View File

@ -1,6 +1,6 @@
# Debugger
Stability: 2 - Stable
> Stability: 2 - Stable
<!-- type=misc -->

2
doc/api/dgram.md
View File

@ -1,6 +1,6 @@
# UDP / Datagram Sockets
Stability: 2 - Stable
> Stability: 2 - Stable
<!-- name=dgram -->

2
doc/api/dns.md
View File

@ -1,6 +1,6 @@
# DNS
Stability: 2 - Stable
> Stability: 2 - Stable
The `dns` module contains functions belonging to two different categories:

2
doc/api/documentation.md
View File

@ -64,7 +64,7 @@ Please do not suggest API changes in this area; they will be refused.
## JSON Output
Stability: 1 - Experimental
> Stability: 1 - Experimental
Every HTML file in the markdown has a corresponding JSON file with the
same data.

6
doc/api/domain.md
View File

@ -1,6 +1,6 @@
# Domain
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
**This module is pending deprecation**. Once a replacement API has been
finalized, this module will be fully deprecated. Most end users should
@ -436,8 +436,8 @@ without exiting the domain.
### domain.dispose()
Stability: 0 - Deprecated. Please recover from failed IO actions
explicitly via error event handlers set on the domain.
> Stability: 0 - Deprecated. Please recover from failed IO actions
> explicitly via error event handlers set on the domain.
Once `dispose` has been called, the domain will no longer be used by callbacks
bound into the domain via `run`, `bind`, or `intercept`, and a `'dispose'` event

4
doc/api/events.md
View File

@ -1,6 +1,6 @@
# Events
Stability: 2 - Stable
> Stability: 2 - Stable
<!--type=module-->
@ -222,7 +222,7 @@ The `'removeListener'` event is emitted *after* the `listener` is removed.
### EventEmitter.listenerCount(emitter, eventName)
Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
A class method that returns the number of listeners for the given `eventName`
registered on the given `emitter`.

8
doc/api/fs.md
View File

@ -1,6 +1,6 @@
# File System
Stability: 2 - Stable
> Stability: 2 - Stable
<!--name=fs-->
@ -584,7 +584,7 @@ added: v0.0.2
deprecated: v1.0.0
-->
Stability: 0 - Deprecated: Use [`fs.stat()`][] or [`fs.access()`][] instead.
> Stability: 0 - Deprecated: Use [`fs.stat()`][] or [`fs.access()`][] instead.
* `path` {String | Buffer}
* `callback` {Function}
@ -610,8 +610,8 @@ added: v0.1.21
deprecated: v1.0.0
-->
Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][]
instead.
> Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][]
> instead.
* `path` {String | Buffer}

2
doc/api/globals.md
View File

@ -155,7 +155,7 @@ Error.
### require.extensions
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* {Object}

4
doc/api/http.md
View File

@ -1,6 +1,6 @@
# HTTP
Stability: 2 - Stable
> Stability: 2 - Stable
To use the HTTP server and client one must `require('http')`.
@ -1331,7 +1331,7 @@ added: v0.1.13
deprecated: v0.3.6
-->
Stability: 0 - Deprecated: Use [`http.request()`][] instead.
> Stability: 0 - Deprecated: Use [`http.request()`][] instead.
Constructs a new HTTP client. `port` and `host` refer to the server to be
connected to.

2
doc/api/https.md
View File

@ -1,6 +1,6 @@
# HTTPS
Stability: 2 - Stable
> Stability: 2 - Stable
HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a
separate module.

2
doc/api/modules.md
View File

@ -1,6 +1,6 @@
# Modules
Stability: 3 - Locked
> Stability: 3 - Locked
<!--name=module-->

4
doc/api/net.md
View File

@ -1,6 +1,6 @@
# net
Stability: 2 - Stable
> Stability: 2 - Stable
The `net` module provides you with an asynchronous network wrapper. It contains
functions for creating both servers and clients (called streams). You can include
@ -98,7 +98,7 @@ added: v0.2.0
deprecated: v0.9.7
-->
Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead.
> Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead.
The number of concurrent connections on the server.

2
doc/api/os.md
View File

@ -1,6 +1,6 @@
# OS
Stability: 2 - Stable
> Stability: 2 - Stable
The `os` module provides a number of operating system-related utility methods.
It can be accessed using:

2
doc/api/path.md
View File

@ -1,6 +1,6 @@
# Path
Stability: 2 - Stable
> Stability: 2 - Stable
The `path` module provides utilities for working with file and directory paths.
It can be accessed using:

2
doc/api/punycode.md
View File

@ -1,6 +1,6 @@
# punycode
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
**The version of the punycode module bundled in Node.js is being deprecated**.
In a future major version of Node.js this module will be removed. Users

2
doc/api/querystring.md
View File

@ -1,6 +1,6 @@
# Query String
Stability: 2 - Stable
> Stability: 2 - Stable
<!--name=querystring-->

2
doc/api/readline.md
View File

@ -1,6 +1,6 @@
# Readline
Stability: 2 - Stable
> Stability: 2 - Stable
The `readline` module provides an interface for reading data from a [Readable][]
stream (such as [`process.stdin`]) one line at a time. It can be accessed using:

4
doc/api/repl.md
View File

@ -1,6 +1,6 @@
# REPL
Stability: 2 - Stable
> Stability: 2 - Stable
The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that
is available both as a standalone program or includable in other applications.
@ -444,7 +444,7 @@ added: v2.0.0
deprecated: v3.0.0
-->
Stability: 0 - Deprecated: Use `NODE_REPL_HISTORY` instead.
> Stability: 0 - Deprecated: Use `NODE_REPL_HISTORY` instead.
Previously in Node.js/io.js v2.x, REPL history was controlled by using a
`NODE_REPL_HISTORY_FILE` environment variable, and the history was saved in JSON

2
doc/api/stream.md
View File

@ -1,6 +1,6 @@
# Stream
Stability: 2 - Stable
> Stability: 2 - Stable
A stream is an abstract interface for working with streaming data in Node.js.
The `stream` module provides a base API that makes it easy to build objects

2
doc/api/string_decoder.md
View File

@ -1,6 +1,6 @@
# StringDecoder
Stability: 2 - Stable
> Stability: 2 - Stable
The `string_decoder` module provides an API for decoding `Buffer` objects into
strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16

2
doc/api/timers.md
View File

@ -1,6 +1,6 @@
# Timers
Stability: 3 - Locked
> Stability: 3 - Locked
The `timer` module exposes a global API for scheduling functions to
be called at some future period of time. Because the timer functions are

8
doc/api/tls.md
View File

@ -1,6 +1,6 @@
# TLS (SSL)
Stability: 2 - Stable
> Stability: 2 - Stable
The `tls` module provides an implementation of the Transport Layer Security
(TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL.
@ -1153,7 +1153,7 @@ added: v0.3.4
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
The `tls.CryptoStream` class represents a stream of encrypted data. This class
has been deprecated and should no longer be used.
@ -1174,7 +1174,7 @@ added: v0.3.2
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
Returned by [`tls.createSecurePair()`][].
@ -1197,7 +1197,7 @@ added: v0.3.2
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
* `context` {Object} A secure context object as returned by
`tls.createSecureContext()`

2
doc/api/tty.md
View File

@ -1,6 +1,6 @@
# TTY
Stability: 2 - Stable
> Stability: 2 - Stable
The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes.
In most cases, it will not be necessary or possible to use this module directly.

2
doc/api/url.md
View File

@ -1,6 +1,6 @@
# URL
Stability: 2 - Stable
> Stability: 2 - Stable
The `url` module provides utilities for URL resolution and parsing. It can be
accessed using:

44
doc/api/util.md
View File

@ -1,6 +1,6 @@
# util
Stability: 2 - Stable
> Stability: 2 - Stable
The `util` module is primarily designed to support the needs of Node.js' own
internal APIs. However, many of the utilities are useful for application and
@ -278,7 +278,7 @@ applications and modules should be updated to find alternative approaches.
### util.debug(string)
Stability: 0 - Deprecated: Use [`console.error()`][] instead.
> Stability: 0 - Deprecated: Use [`console.error()`][] instead.
* `string` {string} The message to print to `stderr`
@ -286,7 +286,7 @@ Deprecated predecessor of `console.error`.
### util.error([...])
Stability: 0 - Deprecated: Use [`console.error()`][] instead.
> Stability: 0 - Deprecated: Use [`console.error()`][] instead.
* `string` {string} The message to print to `stderr`
@ -294,7 +294,7 @@ Deprecated predecessor of `console.error`.
### util.isArray(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -315,7 +315,7 @@ util.isArray({});
### util.isBoolean(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -334,7 +334,7 @@ util.isBoolean(false);
### util.isBuffer(object)
Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead.
> Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead.
* `object` {any}
@ -353,7 +353,7 @@ util.isBuffer(Buffer.from('hello world'));
### util.isDate(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -372,7 +372,7 @@ util.isDate({});
### util.isError(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -407,7 +407,7 @@ util.isError(obj);
### util.isFunction(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -430,7 +430,7 @@ util.isFunction(Bar);
### util.isNull(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -450,7 +450,7 @@ util.isNull(null);
### util.isNullOrUndefined(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -470,7 +470,7 @@ util.isNullOrUndefined(null);
### util.isNumber(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -491,7 +491,7 @@ util.isNumber(NaN);
### util.isObject(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -513,7 +513,7 @@ util.isObject(function(){});
### util.isPrimitive(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -545,7 +545,7 @@ util.isPrimitive(new Date());
### util.isRegExp(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -564,7 +564,7 @@ util.isRegExp({});
### util.isString(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -585,7 +585,7 @@ util.isString(5);
### util.isSymbol(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -604,7 +604,7 @@ util.isSymbol(Symbol('foo'));
### util.isUndefined(object)
Stability: 0 - Deprecated
> Stability: 0 - Deprecated
* `object` {any}
@ -624,7 +624,7 @@ util.isUndefined(null);
### util.log(string)
Stability: 0 - Deprecated: Use a third party module instead.
> Stability: 0 - Deprecated: Use a third party module instead.
* `string` {string}
@ -639,19 +639,19 @@ util.log('Timestamped message.');
### util.print([...])
Stability: 0 - Deprecated: Use [`console.log()`][] instead.
> Stability: 0 - Deprecated: Use [`console.log()`][] instead.
Deprecated predecessor of `console.log`.
### util.puts([...])
Stability: 0 - Deprecated: Use [`console.log()`][] instead.
> Stability: 0 - Deprecated: Use [`console.log()`][] instead.
Deprecated predecessor of `console.log`.
### util._extend(obj)
Stability: 0 - Deprecated: Use [`Object.assign()`] instead.
> Stability: 0 - Deprecated: Use [`Object.assign()`] instead.
The `util._extend()` method was never intended to be used outside of internal
Node.js modules. The community found and used it anyway.

2
doc/api/vm.md
View File

@ -1,6 +1,6 @@
# Executing JavaScript
Stability: 2 - Stable
> Stability: 2 - Stable
<!--name=vm-->

2
doc/api/zlib.md
View File

@ -1,6 +1,6 @@
# Zlib
Stability: 2 - Stable
> Stability: 2 - Stable
The `zlib` module provides compression functionality implemented using Gzip and
Deflate/Inflate. It can be accessed using:

2
tools/doc/README.md
View File

@ -10,7 +10,7 @@ Each type of heading has a description block.
added: v0.10.0
-->
Stability: 3 - Stable
> Stability: 3 - Stable
description and examples.

22
tools/doc/html.js
View File

@ -150,15 +150,31 @@ function parseText(lexed) {
// lists that come right after a heading are what we're after.
function parseLists(input) {
var state = null;
var savedState = [];
var depth = 0;
var output = [];
output.links = input.links;
input.forEach(function(tok) {
if (tok.type === 'code' && tok.text.match(/Stability:.*/g)) {
tok.text = parseAPIHeader(tok.text);
output.push({ type: 'html', text: tok.text });
if (tok.type === 'blockquote_start') {
savedState.push(state);
state = 'MAYBE_STABILITY_BQ';
return;
}
if (tok.type === 'blockquote_end' && state === 'MAYBE_STABILITY_BQ') {
state = savedState.pop();
return;
}
if ((tok.type === 'paragraph' && state === 'MAYBE_STABILITY_BQ') ||
tok.type === 'code') {
if (tok.text.match(/Stability:.*/g)) {
tok.text = parseAPIHeader(tok.text);
output.push({ type: 'html', text: tok.text });
return;
} else if (state === 'MAYBE_STABILITY_BQ') {
output.push({ type: 'blockquote_start' });
state = savedState.pop();
}
}
if (state === null ||
(state === 'AFTERHEADING' && tok.type === 'heading')) {
if (tok.type === 'heading') {

26
tools/doc/json.js
View File

@ -82,19 +82,19 @@ function doJSON(input, filename, cb) {
// Immediately after a heading, we can expect the following
//
// { type: 'code', text: 'Stability: ...' },
// { type: 'blockquote_start' }
// { type: 'paragraph', text: 'Stability: ...' },
// { type: 'blockquote_end' }
//
// a list: starting with list_start, ending with list_end,
// maybe containing other nested lists in each item.
//
// If one of these isnt' found, then anything that comes between
// If one of these isn't found, then anything that comes between
// here and the next heading should be parsed as the desc.
var stability;
if (state === 'AFTERHEADING') {
if (type === 'code' &&
(stability = text.match(/^Stability: ([0-5])(?:\s*-\s*)?(.*)$/))) {
current.stability = parseInt(stability[1], 10);
current.stabilityText = stability[2].trim();
if (type === 'blockquote_start') {
state = 'AFTERHEADING_BLOCKQUOTE';
return;
} else if (type === 'list_start' && !tok.ordered) {
state = 'AFTERHEADING_LIST';
@ -129,6 +129,20 @@ function doJSON(input, filename, cb) {
return;
}
if (state === 'AFTERHEADING_BLOCKQUOTE') {
if (type === 'blockquote_end') {
state = 'AFTERHEADING';
return;
}
if (type === 'paragraph' &&
(stability = text.match(/^Stability: ([0-5])(?:\s*-\s*)?(.*)$/))) {
current.stability = parseInt(stability[1], 10);
current.stabilityText = stability[2].trim();
return;
}
}
current.desc = current.desc || [];
current.desc.push(tok);