Files
node/tools/doc
Rich Trott 3700ba0be3 doc,tools: use only one level 1 header per page
Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: https://github.com/nodejs/node/pull/37839
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Pooja D P <Pooja.D.P@ibm.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
2021-03-25 11:23:58 -07:00
..
2021-02-15 16:14:15 +01:00
2021-01-11 08:13:23 +01:00
…

Here's how the node docs work.

1:1 relationship from lib/<module>.js to doc/api/<module>.md.

Each type of heading has a description block.

# module

<!--introduced_in=v0.10.0-->

> Stability: 2 - Stable

A description and examples.

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

* {type}

A 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?
* `z` {number} How many zebras to bring. **Default:** `100`.

A description of the function.

## module.someNewFunction(x)
<!-- YAML
added: REPLACEME
-->

* `x` {string} The description of the string.

This feature is not in a release yet.

## Event: 'blerg'
<!-- YAML
added: v0.10.0
-->

* `anArg` {type} A description of the listener argument.

Modules don't usually raise events on themselves. `cluster` is the
only exception.

## Class: SomeClass
<!-- YAML
added: v0.10.0
-->

A description of the class.

### 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`.
* Returns: {boolean} `true` if it worked.

A description of the method for humans.

### SomeClass.nextSibling()
<!-- YAML
added: v0.10.0
-->

* Returns: {SomeClass | null} The next `SomeClass` in line.

`SomeClass` must be registered in `tools/doc/type-parser.js`
to be properly parsed in `{type}` fields.

### SomeClass.someProperty
<!-- YAML
added: v0.10.0
-->

* {string}

The indication of what `someProperty` is.

### Event: 'grelb'
<!-- YAML
added: v0.10.0
-->

* `isBlerg` {boolean}

This event is emitted on instances of `SomeClass`, not on the module itself.
  • Classes have (description, Properties, Methods, Events).
  • Events have (list of listener arguments, description).
  • Functions have (list of arguments, returned value if defined, description).
  • Methods have (list of arguments, returned value if defined, description).
  • Modules have (description, Properties, Functions, Classes, Examples).
  • Properties have (type, description).