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

* 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 <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>

tools/doc/README.md

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