1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: fix nits in tools/doc/README.md

Browse Source 
* Sync format schemes with the current doc state.
* Lowercase primitive types.
* Fix typos and unify the style.
* Remove tautological info.

PR-URL: https://github.com/nodejs/node/pull/18874
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
This commit is contained in:
Vse Mozhet Byt 2018-02-20 01:26:58 +02:00
parent 6934792eb3
commit d28edf97fa
1 changed files with 41 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
tools/doc/README.md
View File

@ -1,56 +1,55 @@
Here's how the node docs work. Here's how the node docs work.
1:1 relationship from `lib/<module>.js` to `doc/api/<module>.md` 1:1 relationship from `lib/<module>.js` to `doc/api/<module>.md`.
Each type of heading has a description block. Each type of heading has a description block.
```md ```md
## module # module
<!--introduced_in=v0.10.0-->
> Stability: 2 - Stable
A description and examples.
## module.property
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
> Stability: 3 - Stable * {type}
description and examples. A description of the property.
### module.property ## module.someFunction(x, y, [z=100])
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
* Type * `x` {string} The description of the string.
* `y` {boolean} Should I stay or should I go?
description of the property. * `z` {number} How many zebras to bring.
### 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.
A description of the function. A description of the function.
### module.someNewFunction(x) ## module.someNewFunction(x)
<!-- YAML <!-- YAML
added: REPLACEME 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' ## Event: 'blerg'
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
* Argument: SomeClass object. * `anArg` {type} A description of the listener argument.
Modules don't usually raise events on themselves. `cluster` is the Modules don't usually raise events on themselves. `cluster` is the
only exception. only exception.
## Class: SomeClass ## Class: SomeClass
@ -58,50 +57,50 @@ only exception.
added: v0.10.0 added: v0.10.0
--> -->
description of the class. A description of the class.
### Class Method: SomeClass.classMethod(anArg) ### SomeClass.classMethod(anArg)
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
* `anArg` {Object} Just an argument * `anArg` {Object} Just an argument.
* `field` {String} anArg can have this field. * `field` {string} `anArg` can have this field.
* `field2` {Boolean} Another field. Default: `false`. * `field2` {boolean} Another field. Default: `false`.
* Return: {Boolean} `true` if it worked. * Returns: {boolean} `true` if it worked.
Description of the method for humans. A description of the method for humans.
### someClass.nextSibling() ### SomeClass.nextSibling()
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
* Return: {SomeClass object | null} The next someClass in line. * Returns: {SomeClass | null} The next `SomeClass` in line.
### someClass.someProperty ### SomeClass.someProperty
<!-- YAML <!-- YAML
added: v0.10.0 added: v0.10.0
--> -->
* String * {string}
The indication of what someProperty is. The indication of what `someProperty` is.
### Event: 'grelb' ### Event: 'grelb'
<!-- YAML <!-- YAML
added: v0.10.0 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.
``` ```
* Classes have (description, Properties, Methods, Events) * Classes have (description, Properties, Methods, Events).
* Events have (list of arguments, description) * Events have (list of arguments, description).
* Functions have (list of arguments, description) * Functions have (list of arguments, description).
* Methods have (list of arguments, description) * Methods have (list of arguments, description).
* Modules have (description, Properties, Functions, Classes, Examples) * Modules have (description, Properties, Functions, Classes, Examples).
* Properties have (type, description) * Properties have (type, description).