tools: enable more remark-lint rules

New rules: 1. rule-style 2. strong-marker 3. no-shell-dollars 4. no-inline-padding 5. code-block-style 6. no-multiple-toplevel-headings Fixes to the existing files applied. PR-URL: https://github.com/nodejs/node/pull/8708 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ilkka Myller <ilkka.myller@nodefield.com> Reviewed-By: Johan Bergström <bugs@bergstroem.nu> Reviewed-By: James M Snell <jasnell@gmail.com>
8 years ago · 50be885285
18 changed files with 154 additions and 144 deletions
--- a/.remarkrc
+++ b/.remarkrc
@ -4,7 +4,7 @@
      "blockquote-indentation": 2,
      "checkbox-character-style": { "checked": "x", "unchecked": " " },
      "checkbox-content-indent": true,
-      "code-block-style": false,
+      "code-block-style": "fenced",
      "definition-case": false,
      "definition-spacing": true,
      "emphasis-marker": false,
@ -39,11 +39,11 @@
      "no-heading-indent": true,
      "no-heading-punctuation": false,
      "no-html": false,
-      "no-inline-padding": false,
+      "no-inline-padding": true,
      "no-literal-urls": false,
      "no-missing-blank-lines": false,
-      "no-multiple-toplevel-headings": false,
-      "no-shell-dollars": false,
+      "no-multiple-toplevel-headings": true,
+      "no-shell-dollars": true,
      "no-shortcut-reference-image": true,
      "no-shortcut-reference-link": false,
      "no-table-indentation": true,
@ -52,8 +52,8 @@
      "no-unused-definitions": true,
      "ordered-list-marker-style": false,
      "ordered-list-marker-value": false,
-      "rule-style": false,
-      "strong-marker": false,
+      "rule-style": true,
+      "strong-marker": "*",
      "table-cell-padding": "padded",
      "table-pipe-alignment": false,
      "table-pipes": true,
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -38,9 +38,9 @@ In order for Node.js to stay competitive we need to work on the next generation

 While this constitutes a great leap forward for the platform we will be making this leap without breaking backwards compatibility with the existing ecosystem of modules.

-# Immediate Priorities
+## Immediate Priorities

-## Debugging and Tracing
+### Debugging and Tracing

 Debugging is one of the first things from everyone's mouth, both developer and enterprise, when describing trouble they've had with Node.js.

@ -55,7 +55,7 @@ The [Tracing WG](https://github.com/nodejs/tracing-wg) is driving this effort:
  * [Unify the Tracing endpoint](https://github.com/nodejs/node/issues/729).
  * New Chrome Debugger - Google is working on a version of Chrome's debugger that is without Chrome and can be used with Node.js.

-## Ecosystem Automation
+### Ecosystem Automation

 In order to maintain a good release cadence without harming compatibility we must do a better job of understanding exactly what impact a particular change or release will have on the ecosystem. This requires new automation.

@ -65,19 +65,19 @@ The initial goals for this automation are relatively simple but will create a ba
 * Produce a list of modules that use a particular core API.
 * Produce detailed code coverage data for the tests in core.

-## Improve Installation and Upgrades
+### Improve Installation and Upgrades

 * Host and maintain registry endpoints (Homebrew, apt, etc).
 * Document installation and upgrade procedures with an emphasis on using nvm or nave for development and our registry endpoints for traditional package managers and production.

-## Streams
+### Streams

 * Fix all existing compatibility issues.
 * Simplify stream creation to avoid user error.
 * Explore and identify compatibility issues with [WHATWG Streams](https://github.com/whatwg/streams).
 * Improve stream performance.

-## Internationalization / Localization
+### Internationalization / Localization

 * Build documentation tooling with localization support built in.
 * Reduce size of ICU and ship with it by default.
--- a/doc/api/addons.md
+++ b/doc/api/addons.md
@ -243,7 +243,7 @@ filename to the `sources` array. For example:
 Once the `binding.gyp` file is ready, the example Addons can be configured and
 built using `node-gyp`:

-```sh
+```console
 $ node-gyp configure build
 ```

--- a/doc/api/debugger.md
+++ b/doc/api/debugger.md
@ -181,7 +181,7 @@ localhost:5858

 ## V8 Inspector Integration for Node.js

-__NOTE: This is an experimental feature.__
+**NOTE: This is an experimental feature.**

 V8 Inspector integration allows attaching Chrome DevTools to Node.js
 instances for debugging and profiling.
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@ -6,9 +6,9 @@ The `dns` module contains functions belonging to two different categories:

 1) Functions that use the underlying operating system facilities to perform
 name resolution, and that do not necessarily perform any network communication.
-This category contains only one function: [`dns.lookup()`][]. __Developers
+This category contains only one function: [`dns.lookup()`][]. **Developers
 looking to perform name resolution in the same way that other applications on
-the same operating system behave should use [`dns.lookup()`][].__
+the same operating system behave should use [`dns.lookup()`][].**

 For example, looking up `nodejs.org`.

--- a/doc/api/net.md
+++ b/doc/api/net.md
@ -207,8 +207,10 @@ persist*, they are removed when the last reference to them is closed. Do not
 forget JavaScript string escaping requires paths to be specified with
 double-backslashes, such as:

-    net.createServer().listen(
-        path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
+```js
+net.createServer().listen(
+    path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
+```

 The parameter `backlog` behaves the same as in
 [`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
@ -363,7 +365,7 @@ Emitted when data is received.  The argument `data` will be a `Buffer` or
 `String`.  Encoding of data is set by `socket.setEncoding()`.
 (See the [Readable Stream][] section for more information.)

-Note that the __data will be lost__ if there is no listener when a `Socket`
+Note that the **data will be lost** if there is no listener when a `Socket`
 emits a `'data'` event.

 ### Event: 'drain'
--- a/doc/api/process.md
+++ b/doc/api/process.md
@ -478,7 +478,7 @@ process.argv.forEach((val, index) => {

 Launching the Node.js process as:

-```sh
+```console
 $ node process-2.js one two=three four
 ```

@ -500,7 +500,7 @@ added: 6.4.0
 The `process.argv0` property stores a read-only copy of the original value of
 `argv[0]` passed when Node.js starts.

-```js
+```console
 $ bash -c 'exec -a customArgv0 ./node'
 > process.argv[0]
 '/Volumes/code/external/node/out/Release/node'
@ -672,7 +672,7 @@ It is possible to modify this object, but such modifications will not be
 reflected outside the Node.js process. In other words, the following example
 would not work:

-```sh
+```console
 $ node -e 'process.env.foo = "bar"' && echo $foo
 ```

@ -811,7 +811,7 @@ the same execution environment as the parent.

 For example:

-```sh
+```console
 $ node --harmony script.js --version
 ```

@ -1461,7 +1461,7 @@ in several ways:
 3. Writes _can_ block when output is redirected to a file.
  - Note that disks are fast and operating systems normally employ write-back
    caching so this is very uncommon.
-4. Writes on UNIX __will__ block by default if output is going to a TTY
+4. Writes on UNIX **will** block by default if output is going to a TTY
   (a terminal).
 5. Windows functionality differs. Writes block except when output is going to a
   TTY.
@ -1519,7 +1519,7 @@ in several ways:
 3. Writes _can_ block when output is redirected to a file.
  - Note that disks are fast and operating systems normally employ write-back
    caching so this is very uncommon.
-4. Writes on UNIX __will__ block by default if output is going to a TTY
+4. Writes on UNIX **will** block by default if output is going to a TTY
   (a terminal).
 5. Windows functionality differs. Writes block except when output is going to a
   TTY.
@ -1537,7 +1537,7 @@ To check if Node.js is being run in a [TTY][] context, check the `isTTY`
 property on `process.stderr`, `process.stdout`, or `process.stdin`.

 For instance:
-```sh
+```console
 $ node -p "Boolean(process.stdin.isTTY)"
 true
 $ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
--- a/doc/api/util.md
+++ b/doc/api/util.md
@ -626,7 +626,7 @@ deprecated: v4.0.0

 * `object` {any}

-Returns `true` if the given `object` is strictly an `Object` __and__ not a
+Returns `true` if the given `object` is strictly an `Object` **and** not a
 `Function`. Otherwise, returns `false`.

 ```js
--- a/doc/changelogs/CHANGELOG_ARCHIVE.md
+++ b/doc/changelogs/CHANGELOG_ARCHIVE.md
@ -2175,7 +2175,7 @@ https://github.com/nodejs/node/commit/cfba1f59224ff8602c3fe9145181cad4c6df89a9
  --use-http1

 * Fixes https host header default port handling. (Mikeal Rogers)
-* [#1440](https://github.com/joyent/node/issues/1440) strip byte order marker when loading *.js and *.json files
+* [#1440](https://github.com/joyent/node/issues/1440) strip byte order marker when loading `*.js` and `*.json` files
  (Ben Noordhuis)

 * [#1434](https://github.com/joyent/node/issues/1434) Improve util.format() compatibility with browser. (Koichi Kobayashi)
@ -3089,8 +3089,9 @@ https://github.com/nodejs/node/commit/61c801413544a50000faa7f58376e9b33ba6254f

 https://github.com/nodejs/node/commit/39b63dfe1737d46a8c8818c92773ef181fd174b3

-  * API: - Move process.watchFile into fs module
-         - Move process.inherits to sys
+  * API:
+    - Move process.watchFile into fs module
+    - Move process.inherits to sys

  * Improve Solaris port
  * tcp.Connection.prototype.write now returns boolean to indicate if
@ -3424,7 +3425,7 @@ https://github.com/nodejs/node/commit/726865af7bbafe58435986f4a193ff11c84e4bfe
    - __module becomes module

  * API: Many namespacing changes
-    - Move node.* into process.*
+    - Move node.\* into process.\*
    - Move node.dns into module "dns"
    - Move node.fs into module "posix"
    - process is no longer the global object. GLOBAL is.
--- a/doc/changelogs/CHANGELOG_V4.md
+++ b/doc/changelogs/CHANGELOG_V4.md
@ -1486,11 +1486,11 @@ Maintenance update.

 * Roughly 78% of the commits are documentation and test improvements
 * **domains**:
-** Fix handling of uncaught exceptions (Julien Gilli) [#3884](https://github.com/nodejs/node/pull/3884)
+  * Fix handling of uncaught exceptions (Julien Gilli) [#3884](https://github.com/nodejs/node/pull/3884)
 * **deps**:
-** Upgrade to npm 2.14.12 (Kat Marchán) [#4110](https://github.com/nodejs/node/pull/4110)
-** Backport 819b40a from V8 upstream (Michaël Zasso) [#3938](https://github.com/nodejs/node/pull/3938)
-** Updated node LICENSE file with new npm license (Kat Marchán) [#4110](https://github.com/nodejs/node/pull/4110)
+  * Upgrade to npm 2.14.12 (Kat Marchán) [#4110](https://github.com/nodejs/node/pull/4110)
+  * Backport 819b40a from V8 upstream (Michaël Zasso) [#3938](https://github.com/nodejs/node/pull/3938)
+  * Updated node LICENSE file with new npm license (Kat Marchán) [#4110](https://github.com/nodejs/node/pull/4110)

 ### Known issues

@ -1590,7 +1590,7 @@ Maintenance update.
 * [[`fe3ae3cea4`](https://github.com/nodejs/node/commit/fe3ae3cea4)] - **doc**: add LTS info to COLLABORATOR_GUIDE.md (Myles Borins) [#3442](https://github.com/nodejs/node/pull/3442)
 * [[`daa10a345e`](https://github.com/nodejs/node/commit/daa10a345e)] - **doc**: typo fix in readme.md (Sam P Gallagher-Bishop) [#3649](https://github.com/nodejs/node/pull/3649)
 * [[`eca5720761`](https://github.com/nodejs/node/commit/eca5720761)] - **doc**: fix wrong date and known issue in changelog.md (James M Snell) [#3650](https://github.com/nodejs/node/pull/3650)
-* [[`83494f8f3e`](https://github.com/nodejs/node/commit/83494f8f3e)] - **doc**: rename iojs-* groups to nodejs-* (Steven R. Loomis) [#3634](https://github.com/nodejs/node/pull/3634)
+* [[`83494f8f3e`](https://github.com/nodejs/node/commit/83494f8f3e)] - **doc**: rename iojs-\* groups to nodejs-\* (Steven R. Loomis) [#3634](https://github.com/nodejs/node/pull/3634)
 * [[`347fb65aee`](https://github.com/nodejs/node/commit/347fb65aee)] - **doc**: fix crypto spkac function descriptions (Jason Gerfen) [#3614](https://github.com/nodejs/node/pull/3614)
 * [[`11d2050d63`](https://github.com/nodejs/node/commit/11d2050d63)] - **doc**: Updated streams simplified constructor API (Tom Gallacher) [#3602](https://github.com/nodejs/node/pull/3602)
 * [[`6db4392bfb`](https://github.com/nodejs/node/commit/6db4392bfb)] - **doc**: made code spans more visible in the API docs (phijohns) [#3573](https://github.com/nodejs/node/pull/3573)
--- a/doc/changelogs/CHANGELOG_V5.md
+++ b/doc/changelogs/CHANGELOG_V5.md
@ -1499,7 +1499,7 @@ This is an important security release. All Node.js users should consult the secu
 * [[`b14d9c5f16`](https://github.com/nodejs/node/commit/b14d9c5f16)] - **doc**: add method links in events.markdown (Alejandro Oviedo) [#3187](https://github.com/nodejs/node/pull/3187)
 * [[`44f779b112`](https://github.com/nodejs/node/commit/44f779b112)] - **doc**: add caveats of algs and key size in crypto (Shigeki Ohtsu) [#3479](https://github.com/nodejs/node/pull/3479)
 * [[`a0db5fb355`](https://github.com/nodejs/node/commit/a0db5fb355)] - **doc**: stdout/stderr can block when directed to file (Ben Noordhuis) [#3170](https://github.com/nodejs/node/pull/3170)
-* [[`409f29972e`](https://github.com/nodejs/node/commit/409f29972e)] - **doc**: rename iojs-* groups to nodejs-* (Steven R. Loomis) [#3634](https://github.com/nodejs/node/pull/3634)
+* [[`409f29972e`](https://github.com/nodejs/node/commit/409f29972e)] - **doc**: rename iojs-\* groups to nodejs-\* (Steven R. Loomis) [#3634](https://github.com/nodejs/node/pull/3634)
 * [[`801866280e`](https://github.com/nodejs/node/commit/801866280e)] - **doc**: fix wrong date and known issue in changelog.md (James M Snell) [#3650](https://github.com/nodejs/node/pull/3650)
 * [[`325c4c7af5`](https://github.com/nodejs/node/commit/325c4c7af5)] - **doc**: fix function param order in assert doc (David Woods) [#3533](https://github.com/nodejs/node/pull/3533)
 * [[`045e04e531`](https://github.com/nodejs/node/commit/045e04e531)] - **doc**: typo fix in readme.md (Sam P Gallagher-Bishop) [#3649](https://github.com/nodejs/node/pull/3649)
--- a/doc/ctc-meetings/2016-06-15.md
+++ b/doc/ctc-meetings/2016-06-15.md
@ -42,8 +42,8 @@ Extracted from **ctc-agenda** labelled issues and pull requests from the **nodej
    * some issue/PRs reviews

 * Chris Dickinson @chrisdickinson (CTC)
-      * NodeConf
-      * modules.guide
+    * NodeConf
+    * modules.guide

 * Evan Lucas @evanlucas (CTC)
    * Preparing for security release
--- a/doc/guides/timers-in-node.md
+++ b/doc/guides/timers-in-node.md
@ -82,7 +82,7 @@ console.log('after immediate');
 The above function passed to `setImmediate()` will execute after all runnable
 code has executed, and the console output will be:

-```shell
+```console
 before immediate
 after immediate
 executing immediate: so immediate
--- a/doc/releases.md
+++ b/doc/releases.md
@ -34,7 +34,7 @@ A SHASUMS256.txt file is produced for every promoted build, nightly, and release

 The GPG keys should be fetchable from a known third-party keyserver. The SKS Keyservers at <https://sks-keyservers.net> are recommended. Use the [submission](https://sks-keyservers.net/i/#submit) form to submit a new GPG key. Keys should be fetchable via:

-```sh
+```console
 $ gpg --keyserver pool.sks-keyservers.net --recv-keys <FINGERPRINT>
 ```

@ -55,7 +55,7 @@ Create a new branch named _"vx.y.z-proposal"_, or something similar. Using `git

 For a list of commits that could be landed in a patch release on v5.x

-```sh
+```console
 $ branch-diff v5.x master --exclude-label=semver-major,semver-minor,dont-land-on-v5.x --filter-release --format=simple
 ```

@ -94,13 +94,13 @@ The general rule is to bump this version when there are _breaking ABI_ changes a

 Collect a formatted list of commits since the last release. Use [`changelog-maker`](https://github.com/rvagg/changelog-maker) to do this.

-```sh
+```console
 $ changelog-maker --group
 ```

 Note that changelog-maker counts commits since the last tag and if the last tag in the repository was not on the current branch you may have to supply a `--start-ref` argument:

-```sh
+```console
 $ changelog-maker --group --start-ref v2.3.1
 ```

@ -224,7 +224,7 @@ $ npm install -g git-secure-tag

 Create a tag using the following command:

-```sh
+```console
 $ git secure-tag <vx.y.z> <commit-sha> -sm 'YYYY-MM-DD Node.js vx.y.z (Release Type) Release'
 ```

@ -232,7 +232,7 @@ The tag **must** be signed using the GPG key that's listed for you on the projec

 Push the tag to the repo before you promote the builds. If you haven't pushed your tag first, then build promotion won't work properly. Push the tag using the following command:

-```sh
+```console
 $ git push <remote> <vx.y.z>
 ```

--- a/doc/topics/the-event-loop-timers-and-nexttick.md
+++ b/doc/topics/the-event-loop-timers-and-nexttick.md
@ -22,24 +22,26 @@ this document) which may make async API calls, schedule timers, or call
 The following diagram shows a simplified overview of the event loop's
 order of operations.

-       ┌───────────────────────┐
-    ┌─>│        timers         │
-    │  └──────────┬────────────┘
-    │  ┌──────────┴────────────┐
-    │  │     I/O callbacks     │
-    │  └──────────┬────────────┘
-    │  ┌──────────┴────────────┐
-    │  │     idle, prepare     │
-    │  └──────────┬────────────┘      ┌───────────────┐
-    │  ┌──────────┴────────────┐      │   incoming:   │
-    │  │         poll          │<─────┤  connections, │
-    │  └──────────┬────────────┘      │   data, etc.  │
-    │  ┌──────────┴────────────┐      └───────────────┘
-    │  │        check          │
-    │  └──────────┬────────────┘
-    │  ┌──────────┴────────────┐
-    └──┤    close callbacks    │
-       └───────────────────────┘
+```txt
+   ┌───────────────────────┐
+┌─>│        timers         │
+│  └──────────┬────────────┘
+│  ┌──────────┴────────────┐
+│  │     I/O callbacks     │
+│  └──────────┬────────────┘
+│  ┌──────────┴────────────┐
+│  │     idle, prepare     │
+│  └──────────┬────────────┘      ┌───────────────┐
+│  ┌──────────┴────────────┐      │   incoming:   │
+│  │         poll          │<─────┤  connections, │
+│  └──────────┬────────────┘      │   data, etc.  │
+│  ┌──────────┴────────────┐      └───────────────┘
+│  │        check          │
+│  └──────────┬────────────┘
+│  ┌──────────┴────────────┐
+└──┤    close callbacks    │
+   └───────────────────────┘
+```

 *note: each box will be referred to as a "phase" of the event loop.*

@ -238,13 +240,15 @@ setImmediate(function immediate () {
 });
 ```

-    $ node timeout_vs_immediate.js
-    timeout
-    immediate
+```console
+$ node timeout_vs_immediate.js
+timeout
+immediate

-    $ node timeout_vs_immediate.js
-    immediate
-    timeout
+$ node timeout_vs_immediate.js
+immediate
+timeout
+```

 However, if you move the two calls within an I/O cycle, the immediate
 callback is always executed first:
@ -263,13 +267,15 @@ fs.readFile(__filename, () => {
 })
 ```

-    $ node timeout_vs_immediate.js
-    immediate
-    timeout
+```console
+$ node timeout_vs_immediate.js
+immediate
+timeout

-    $ node timeout_vs_immediate.js
-    immediate
-    timeout
+$ node timeout_vs_immediate.js
+immediate
+timeout
+```

 The main advantage to using `setImmediate()` over `setTimeout()` is
 `setImmediate()` will always be executed before any timers if scheduled
--- a/doc/tsc-meetings/2015-08-26.md
+++ b/doc/tsc-meetings/2015-08-26.md
@ -18,7 +18,7 @@ Extracted from **tsc-agenda** labelled issues and pull requests in the nodejs or
 ### nodejs/node

 * doc: merge CHANGELOG.md with joyent/node ChangeLog [#2536](https://github.com/nodejs/node/pull/2536)
-* (guidance on) rename of "language groups" from iojs-* to nodejs-*? [#2525](https://github.com/nodejs/node/issues/2525)
+* (guidance on) rename of "language groups" from iojs-\* to nodejs-\*? [#2525](https://github.com/nodejs/node/issues/2525)
 * Node.js v4 Release Timeline [#2522](https://github.com/nodejs/node/issues/2522)

 ### nodejs/collaboration
@ -76,7 +76,7 @@ Target ETA for transition: Monday.
 * Rod seeking confirmation from this group that this was _not a bad idea_.
 * Discussion about documentation for people upgrading from older versions of Node and having a linear history. Jeremiah has been working on 0.10 -> v4 documentation.

-### (guidance on) rename of "language groups" from iojs-* to nodejs-*? [#2525](https://github.com/nodejs/node/issues/2525)
+### (guidance on) rename of "language groups" from iojs-\* to nodejs-\*? [#2525](https://github.com/nodejs/node/issues/2525)

 * Steven discussed renaming the language groups
 * Mikeal: some groups are not in a position to make decisions because they are not active but the ones that are should be given the opportunity to agree or disagree to the move rather than us imposing a move on them. We should post an issue in their repos.
--- a/doc/tsc-meetings/2015-10-14.md
+++ b/doc/tsc-meetings/2015-10-14.md
@ -45,7 +45,7 @@ Extracted from **tsc-agenda** labelled issues and pull requests in the nodejs or
 * Rod Vagg: Not quite as involved, took a bit of time off. Getting back up to speed on build
 * Domenic: Nothing this week
 * Brian: PRs & Issues
-* Steven: Worked on getting ICU 56.1 out and into v4.2.0 LTS, working on making the ICU [install better](https://github.com/nodejs/node-v0.x-archive/issues/8996#issuecomment-89411193). Also shepherding iojs-* rename to nodejs-* [#2525](https://github.com/nodejs/node/issues/2525)
+* Steven: Worked on getting ICU 56.1 out and into v4.2.0 LTS, working on making the ICU [install better](https://github.com/nodejs/node-v0.x-archive/issues/8996#issuecomment-89411193). Also shepherding iojs-\* rename to nodejs-\* [#2525](https://github.com/nodejs/node/issues/2525)
 * James: Worked on the 4.2.0 and 4.2.1 releases. Working on the cgitm smoke-testing tool and http WG.
 * Michael: Worked on adding pLinux to the CI. Looking into running the tests on fips-compliant mode. Investigated some AIX issues.
 * Ben: PRs & Issues, doing some work on the debugger and memory bugs in libuv
--- a/tools/doc/README.md
+++ b/tools/doc/README.md
@ -4,98 +4,99 @@ Here's how the node docs work.

 Each type of heading has a description block.

+```md
+## module
+<!-- YAML
+added: v0.10.0
+-->

-    ## module
-    <!-- YAML
-    added: v0.10.0
-    -->
+> Stability: 3 - Stable

-    > Stability: 3 - Stable
+description and examples.

-    description and examples.
+### module.property
+<!-- YAML
+added: v0.10.0
+-->

-    ### module.property
-    <!-- YAML
-    added: v0.10.0
-    -->
+* Type

-    * Type
+description of the property.

-    description of the property.
+### module.someFunction(x, y, [z=100])
+<!-- YAML
+added: v0.10.0
+-->

-    ### 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?
+* `z` {Number} How many zebras to bring.

-    * `x` {String} the description of the string
-    * `y` {Boolean} Should I stay or should I go?
-    * `z` {Number} How many zebras to bring.
+A description of the function.

-    A description of the function.
+### module.someNewFunction(x)
+<!-- YAML
+added: REPLACEME
+-->

-    ### module.someNewFunction(x)
-    <!-- YAML
-    added: REPLACEME
-    -->
+* `x` {String} the description of the string

-    * `x` {String} the description of the string
+This feature is not in a release yet.

-    This feature is not in a release yet.
+### Event: 'blerg'
+<!-- YAML
+added: v0.10.0
+-->

-    ### Event: 'blerg'
-    <!-- YAML
-    added: v0.10.0
-    -->
+* Argument: SomeClass object.

-    * Argument: SomeClass object.
+Modules don't usually raise events on themselves.  `cluster` is the
+only exception.

-    Modules don't usually raise events on themselves.  `cluster` is the
-    only exception.
+## Class: SomeClass
+<!-- YAML
+added: v0.10.0
+-->

-    ## Class: SomeClass
-    <!-- YAML
-    added: v0.10.0
-    -->
+description of the class.

-    description of the class.
+### Class Method: SomeClass.classMethod(anArg)
+<!-- YAML
+added: v0.10.0
+-->

-    ### Class Method: SomeClass.classMethod(anArg)
-    <!-- YAML
-    added: v0.10.0
-    -->
+* `anArg` {Object}  Just an argument
+  * `field` {String} anArg can have this field.
+  * `field2` {Boolean}  Another field.  Default: `false`.
+* Return: {Boolean} `true` if it worked.

-    * `anArg` {Object}  Just an argument
-      * `field` {String} anArg can have this field.
-      * `field2` {Boolean}  Another field.  Default: `false`.
-    * Return: {Boolean} `true` if it worked.
+Description of the method for humans.

-    Description of the method for humans.
+### someClass.nextSibling()
+<!-- YAML
+added: v0.10.0
+-->

-    ### someClass.nextSibling()
-    <!-- YAML
-    added: v0.10.0
-    -->
+* Return: {SomeClass object | null}  The next someClass in line.

-    * Return: {SomeClass object | null}  The next someClass in line.
+### someClass.someProperty
+<!-- YAML
+added: v0.10.0
+-->

-    ### someClass.someProperty
-    <!-- YAML
-    added: v0.10.0
-    -->
+* String

-    * String
+The indication of what someProperty is.

-    The indication of what someProperty is.
+### Event: 'grelb'
+<!-- YAML
+added: v0.10.0
+-->

-    ### Event: 'grelb'
-    <!-- YAML
-    added: v0.10.0
-    -->
+* `isBlerg` {Boolean}

-    * `isBlerg` {Boolean}
-
-    This event is emitted on instances of SomeClass, not on the module itself.
+This event is emitted on instances of SomeClass, not on the module itself.
+```


 * Modules have (description, Properties, Functions, Classes, Examples)