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>

doc/api/assert.md

@@ -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

doc/api/buffer.md

@@ -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

doc/api/child_process.md

@@ -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

doc/api/cluster.md

@@ -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

doc/api/console.md

@@ -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.

doc/api/crypto.md

@@ -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.
@@ -495,7 +495,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 `'binary'`,
 `'hex'` or `'base64'`. If `encoding` is provided `public_key` is expected to
@@ -892,7 +892,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()`

doc/api/debugger.md

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

doc/api/dgram.md

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

doc/api/dns.md

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

doc/api/documentation.md

@@ -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.

doc/api/domain.md

@@ -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

doc/api/events.md

@@ -1,6 +1,6 @@
 # Events
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 <!--type=module-->
 
@@ -244,7 +244,7 @@ The `'removeListener'` event is emitted *after* a 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`.

doc/api/fs.md

@@ -1,6 +1,6 @@
 # File System
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 <!--name=fs-->
 
@@ -476,7 +476,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.
 
 Test whether or not the given path exists by checking with the file system.
 Then call the `callback` argument with either true or false.  Example:
@@ -499,7 +499,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.
 
 Synchronous version of [`fs.exists()`][].
 Returns `true` if the file exists, `false` otherwise.

doc/api/globals.md

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

doc/api/http.md

@@ -1,6 +1,6 @@
 # HTTP
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 To use the HTTP server and client one must `require('http')`.
 
@@ -1274,7 +1274,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.

doc/api/https.md

@@ -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.

doc/api/modules.md

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

doc/api/net.md

@@ -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
@@ -97,7 +97,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.
 

doc/api/os.md

@@ -1,6 +1,6 @@
 # OS
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 Provides a few basic operating-system related utility functions.
 

doc/api/path.md

@@ -1,6 +1,6 @@
 # Path
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 This module contains utilities for handling and transforming file
 paths.  Almost all these methods perform only string transformations.

doc/api/punycode.md

@@ -1,6 +1,6 @@
 # punycode
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 [Punycode.js][] is bundled with Node.js v0.5.1+. Use `require('punycode')` to
 access it. (To use it with other Node.js versions, use npm to install the

doc/api/querystring.md

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

doc/api/readline.md

@@ -1,6 +1,6 @@
 # Readline
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 To use this module, do `require('readline')`. Readline allows reading of a
 stream (such as [`process.stdin`][]) on a line-by-line basis.

doc/api/repl.md

@@ -1,6 +1,6 @@
 # REPL
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 A Read-Eval-Print-Loop (REPL) is available both as a standalone program and
 easily includable in other programs. The REPL provides a way to interactively
@@ -56,7 +56,7 @@ disabled by setting the environment variable `NODE_REPL_HISTORY=""`.
 
 ### NODE_REPL_HISTORY_FILE
 
-    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

doc/api/stream.md

@@ -1,6 +1,6 @@
 # Stream
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 A stream is an abstract interface implemented by various objects in
 Node.js. For example a [request to an HTTP server][http-incoming-message] is a

doc/api/string_decoder.md

@@ -1,6 +1,6 @@
 # StringDecoder
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 To use this module, do `require('string_decoder')`. StringDecoder decodes a
 buffer to a string. It is a simple interface to `buffer.toString()` but provides

doc/api/timers.md

@@ -1,6 +1,6 @@
 # Timers
 
-    Stability: 3 - Locked
+> Stability: 3 - Locked
 
 All of the timer functions are globals.  You do not need to `require()`
 this module in order to use them.

doc/api/tls.md

@@ -1,6 +1,6 @@
 # TLS (SSL)
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 Use `require('tls')` to access this module.
 
@@ -159,7 +159,7 @@ is expensive.
 
 ## Class: CryptoStream
 
-    Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
 
 This is an encrypted stream.
 

doc/api/tty.md

@@ -1,6 +1,6 @@
 # TTY
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 The `tty` module houses the `tty.ReadStream` and `tty.WriteStream` classes. In
 most cases, you will not need to use this module directly.
@@ -95,6 +95,6 @@ terminal.
 
 ## tty.setRawMode(mode)
 
-    Stability: 0 - Deprecated: Use [tty.ReadStream#setRawMode][] (i.e. process.stdin.setRawMode) instead.
+> Stability: 0 - Deprecated: Use [tty.ReadStream#setRawMode][] (i.e. process.stdin.setRawMode) instead.
 
 [tty.ReadStream#setRawMode]: #tty_rs_setrawmode_mode

doc/api/url.md

@@ -1,6 +1,6 @@
 # URL
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 This module has utilities for URL resolution and parsing.
 Call `require('url')` to use it.

doc/api/util.md

@@ -1,6 +1,6 @@
 # util
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 These functions are in the module `'util'`. Use `require('util')` to
 access them.
@@ -14,7 +14,7 @@ are unnecessary for Node.js's internal functionality.
 
 ## util.debug(string)
 
-    Stability: 0 - Deprecated: Use [`console.error()`][] instead.
+> Stability: 0 - Deprecated: Use [`console.error()`][] instead.
 
 Deprecated predecessor of `console.error`.
 
@@ -83,7 +83,7 @@ when the deprecated API is used.  Configurable at run-time through the
 
 ## util.error([...])
 
-    Stability: 0 - Deprecated: Use [`console.error()`][] instead.
+> Stability: 0 - Deprecated: Use [`console.error()`][] instead.
 
 Deprecated predecessor of `console.error`.
 
@@ -250,7 +250,7 @@ util.inspect(obj);
 
 ## util.isArray(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Internal alias for [`Array.isArray`][].
 
@@ -269,7 +269,7 @@ util.isArray({})
 
 ## util.isBoolean(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `Boolean`. Otherwise, returns `false`.
 
@@ -286,7 +286,7 @@ util.isBoolean(false)
 
 ## util.isBuffer(object)
 
-    Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead.
+> Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead.
 
 Returns `true` if the given "object" is a `Buffer`. Otherwise, returns `false`.
 
@@ -303,7 +303,7 @@ util.isBuffer(new Buffer('hello world'))
 
 ## util.isDate(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `Date`. Otherwise, returns `false`.
 
@@ -320,7 +320,7 @@ util.isDate({})
 
 ## util.isError(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is an [`Error`][]. Otherwise, returns
 `false`.
@@ -338,7 +338,7 @@ util.isError({ name: 'Error', message: 'an error occurred' })
 
 ## util.isFunction(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `Function`. Otherwise, returns
 `false`.
@@ -359,7 +359,7 @@ util.isFunction(Bar)
 
 ## util.isNull(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is strictly `null`. Otherwise, returns
 `false`.
@@ -377,7 +377,7 @@ util.isNull(null)
 
 ## util.isNullOrUndefined(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is `null` or `undefined`. Otherwise,
 returns `false`.
@@ -395,7 +395,7 @@ util.isNullOrUndefined(null)
 
 ## util.isNumber(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `Number`. Otherwise, returns `false`.
 
@@ -414,7 +414,7 @@ util.isNumber(NaN)
 
 ## util.isObject(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is strictly an `Object` __and__ not a
 `Function`. Otherwise, returns `false`.
@@ -434,7 +434,7 @@ util.isObject(function(){})
 
 ## util.isPrimitive(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a primitive type. Otherwise, returns
 `false`.
@@ -464,7 +464,7 @@ util.isPrimitive(new Date())
 
 ## util.isRegExp(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `RegExp`. Otherwise, returns `false`.
 
@@ -481,7 +481,7 @@ util.isRegExp({})
 
 ## util.isString(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `String`. Otherwise, returns `false`.
 
@@ -500,7 +500,7 @@ util.isString(5)
 
 ### util.isSymbol(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is a `Symbol`. Otherwise, returns `false`.
 
@@ -517,7 +517,7 @@ util.isSymbol(Symbol('foo'))
 
 ## util.isUndefined(object)
 
-    Stability: 0 - Deprecated
+> Stability: 0 - Deprecated
 
 Returns `true` if the given "object" is `undefined`. Otherwise, returns `false`.
 
@@ -541,19 +541,19 @@ Output with timestamp on `stdout`.
 
 ## util.print([...])
 
-    Stability: 0 - Deprecated: Use [`console.log()`][] instead.
+> Stability: 0 - Deprecated: Use [`console.log()`][] instead.
 
 Deprecated predecessor of `console.log`.
 
 ## util.pump(readableStream, writableStream[, callback])
 
-    Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
+> Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
 
 Deprecated predecessor of `stream.pipe()`.
 
 ## util.puts([...])
 
-    Stability: 0 - Deprecated: Use [`console.log()`][] instead.
+> Stability: 0 - Deprecated: Use [`console.log()`][] instead.
 
 Deprecated predecessor of `console.log`.
 

doc/api/v8.md

@@ -1,6 +1,6 @@
 # V8
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 This module exposes events and interfaces specific to the version of [V8][]
 built with Node.js.  These interfaces are subject to change by upstream and are

doc/api/vm.md

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

doc/api/zlib.md

@@ -1,6 +1,6 @@
 # Zlib
 
-    Stability: 2 - Stable
+> Stability: 2 - Stable
 
 You can access this module with:
 

tools/doc/README.md

@@ -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.
 

tools/doc/html.js

@@ -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') {

tools/doc/json.js

@@ -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);