From f391181b27d949c72835abae5d6ccf0978de85e4 Mon Sep 17 00:00:00 2001
From: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Date: Sun, 15 Apr 2018 16:56:12 +0300
Subject: [PATCH] doc: update tools/doc/README.md

PR-URL: https://github.com/nodejs/node/pull/20047
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
---
 tools/doc/README.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/tools/doc/README.md b/tools/doc/README.md
index 2d5317db9e6fd7..8c183b38989684 100644
--- a/tools/doc/README.md
+++ b/tools/doc/README.md
@@ -29,7 +29,7 @@ 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.
+* `z` {number} How many zebras to bring. **Default:** `100`.
 
 A description of the function.
 
@@ -66,7 +66,7 @@ added: v0.10.0
 
 * `anArg` {Object} Just an argument.
   * `field` {string} `anArg` can have this field.
-  * `field2` {boolean} Another field. Default: `false`.
+  * `field2` {boolean} Another field. **Default:** `false`.
 * Returns: {boolean} `true` if it worked.
 
 A description of the method for humans.
@@ -78,6 +78,9 @@ 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
@@ -99,8 +102,8 @@ 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).
+* 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).