nodejs

mirror of https://github.com/nodejs/node.git synced 2024-11-30 07:27:22 +01:00

History

Rich Trott b6cd2155c3 doc: remove em dashes Our documentation uses em dashes inconsistently. They are treated inconsistently typographically too. (For example, they are sometimes surrounded by spaces and sometimes not.) They are also often confused with ordinary hyphens such as in the CHANGELOG, where they are inadvertently mixed together in a single list. The difference is not obvious in the raw markdown but is very noticeable when rendered, appearing to be a typographical error (which it in fact is). The em dash is never needed. There are always alternatives. Remove em dashes entirely. PR-URL: https://github.com/nodejs/node/pull/32080 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>		2020-03-05 22:25:42 -08:00
..
addon-verify.js
allhtml.js
alljson.js
apilinks.js
common.js
generate.js	tools: add unified plugin changing links for html docs	2019-11-30 18:17:56 +01:00
html.js	test: fix flaky doctool and test	2019-10-15 13:22:41 -07:00
json.js	tools: update JSON header parsing for backticks	2020-01-12 07:10:33 -08:00
LICENSE
links-mapper.json	tools: add unified plugin changing links for html docs	2019-11-30 18:17:56 +01:00
markdown.js	tools: add unified plugin changing links for html docs	2019-11-30 18:17:56 +01:00
package-lock.json
package.json	tools: doc: improve async workflow of generate.js	2019-10-27 10:08:22 +01:00
README.md	doc: prepare markdown files for more stringent blank-line linting	2019-09-07 07:07:25 -07:00
type-parser.js	stream: support passing generator functions into pipeline()	2020-01-17 16:50:07 -08:00
versions.js	doc: remove em dashes	2020-03-05 22:25:42 -08:00

README.md

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