Skip to content

Commit

Permalink
doc: fix nits in tools/doc/README.md
Browse files Browse the repository at this point in the history
* Sync format schemes with the current doc state.
* Lowercase primitive types.
* Fix typos and unify the style.
* Remove tautological info.

PR-URL: #18874
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
  • Loading branch information
vsemozhetbyt authored and MylesBorins committed Feb 21, 2018
1 parent a40c28b commit b9b5810
Showing 1 changed file with 38 additions and 39 deletions.
77 changes: 38 additions & 39 deletions tools/doc/README.md
Original file line number Diff line number Diff line change
@@ -1,107 +1,106 @@
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.

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

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

> Stability: 3 - Stable
> Stability: 2 - Stable

description and examples.
A description and examples.

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

* Type
* {type}

description of the property.
A description of the property.

### module.someFunction(x, y, [z=100])
## 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.

### module.someNewFunction(x)
## 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.

### Event: 'blerg'
## Event: 'blerg'
<!-- YAML
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.

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

description of the class.
A description of the class.

### Class Method: SomeClass.classMethod(anArg)
### 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`.
* Returns: {boolean} `true` if it worked.

Description of the method for humans.
A description of the method for humans.

### someClass.nextSibling()
### SomeClass.nextSibling()
<!-- YAML
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
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
-->

* `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)
* Events have (list of arguments, description)
* Functions have (list of arguments, description)
* Methods have (list of arguments, description)
* Modules have (description, Properties, Functions, Classes, Examples)
* Properties have (type, description)
* Classes have (description, Properties, Methods, Events).
* Events have (list of arguments, description).
* Functions have (list of arguments, description).
* Methods have (list of arguments, description).
* Modules have (description, Properties, Functions, Classes, Examples).
* Properties have (type, description).

0 comments on commit b9b5810

Please sign in to comment.