From 9a18b0e668e136b75de4e7b92373193bbd50be08 Mon Sep 17 00:00:00 2001
From: Sho Miyamoto <shqld8@gmail.com>
Date: Wed, 14 Feb 2018 16:17:14 +0900
Subject: [PATCH] doc: add missing `Returns` in fs & util

PR-URL: https://github.com/nodejs/node/pull/18775
Reviewed-By: Weijia Wang <starkwang@126.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
---
 doc/api/fs.md   | 16 ++++++++++++++++
 doc/api/util.md | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 2210d7ecb3b96f..15afc61e567efc 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1207,6 +1207,7 @@ changes:
   * `start` {integer}
   * `end` {integer}
   * `highWaterMark` {integer}
+* Returns: {stream.Readable}
 
 Returns a new [`ReadStream`][] object. (See [Readable Streams][]).
 
@@ -1282,6 +1283,7 @@ changes:
   * `mode` {integer}
   * `autoClose` {boolean}
   * `start` {integer}
+* Returns: {stream.Writable}
 
 Returns a new [`WriteStream`][] object. (See [Writable Stream][]).
 
@@ -1439,6 +1441,7 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
+* Returns: {boolean}
 
 Synchronous version of [`fs.exists()`][].
 Returns `true` if the path exists, `false` otherwise.
@@ -1557,6 +1560,7 @@ added: v0.1.95
 -->
 
 * `fd` {integer}
+* Returns: {fs.Stats}
 
 Synchronous fstat(2). Returns an instance of [`fs.Stats`][].
 
@@ -1831,6 +1835,7 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
+* Returns: {fs.Stats}
 
 Synchronous lstat(2). Returns an instance of [`fs.Stats`][].
 
@@ -1956,6 +1961,7 @@ added: v5.10.0
 * `prefix` {string}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
+* Returns: {string}
 
 The synchronous version of [`fs.mkdtemp()`][]. Returns the created
 folder path.
@@ -2080,6 +2086,7 @@ changes:
 * `path` {string|Buffer|URL}
 * `flags` {string|number}
 * `mode` {integer} **Default:** `0o666`
+* Returns: {number}
 
 Synchronous version of [`fs.open()`][]. Returns an integer representing the file
 descriptor.
@@ -2170,6 +2177,7 @@ changes:
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
+* Returns: {Array} An array of filenames
 
 Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
 `'..'`.
@@ -2270,6 +2278,7 @@ changes:
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
   * `flag` {string} **Default:** `'r'`
+* Returns: {string|Buffer}
 
 Synchronous version of [`fs.readFile()`][]. Returns the contents of the `path`.
 
@@ -2330,6 +2339,7 @@ changes:
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
+* Returns: {string|Buffer}
 
 Synchronous readlink(2). Returns the symbolic link's string value.
 
@@ -2352,6 +2362,7 @@ changes:
 * `offset` {integer}
 * `length` {integer}
 * `position` {integer}
+* Returns: {number}
 
 Synchronous version of [`fs.read()`][]. Returns the number of `bytesRead`.
 
@@ -2462,6 +2473,7 @@ changes:
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
+* Returns: {string|Buffer}
 
 Synchronously computes the canonical pathname by resolving `.`, `..` and
 symbolic links.
@@ -2492,6 +2504,7 @@ added: v9.2.0
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
+* Returns: {string|Buffer}
 
 Synchronous realpath(3).
 
@@ -2629,6 +2642,7 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
+* Returns: {fs.Stats}
 
 Synchronous stat(2). Returns an instance of [`fs.Stats`][].
 
@@ -3194,6 +3208,7 @@ changes:
 * `offset` {integer}
 * `length` {integer}
 * `position` {integer}
+* Returns: {number}
 
 ## fs.writeSync(fd, string[, position[, encoding]])
 <!-- YAML
@@ -3208,6 +3223,7 @@ changes:
 * `string` {string}
 * `position` {integer}
 * `encoding` {string}
+* Returns: {number}
 
 Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
 
diff --git a/doc/api/util.md b/doc/api/util.md
index 4201e7dfd2e0bf..2ad5a6f3365cf1 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -216,6 +216,7 @@ contains circular references.
   object formatting. Similar to `util.inspect()` without options. This will show
   the full object not including non-enumerable properties and proxies.
 * `%%` - single percent sign (`'%'`). This does not consume an argument.
+* Returns: {string} The formatted string
 
 If the placeholder does not have a corresponding argument, the placeholder is
 not replaced.
@@ -397,6 +398,7 @@ changes:
     This is useful to minimize the inspection output for large complicated
     objects. To make it recurse indefinitely pass `null` or `Infinity`. Defaults
     to `Infinity`.
+* Returns: {string} The representation of passed object
 
 The `util.inspect()` method returns a string representation of `object` that is
 intended for debugging. The output of `util.inspect` may change at any time
@@ -944,6 +946,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Internal alias for [`Array.isArray`][].
 
@@ -969,6 +972,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`.
 
@@ -992,6 +996,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead.
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`.
 
@@ -1015,6 +1020,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`.
 
@@ -1038,6 +1044,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns
 `false`.
@@ -1077,6 +1084,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Function`. Otherwise, returns
 `false`.
@@ -1104,6 +1112,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is strictly `null`. Otherwise, returns
 `false`.
@@ -1128,6 +1137,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is `null` or `undefined`. Otherwise,
 returns `false`.
@@ -1152,6 +1162,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`.
 
@@ -1177,6 +1188,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is strictly an `Object` **and** not a
 `Function`. Otherwise, returns `false`.
@@ -1203,6 +1215,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a primitive type. Otherwise, returns
 `false`.
@@ -1239,6 +1252,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`.
 
@@ -1262,6 +1276,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `string`. Otherwise, returns `false`.
 
@@ -1287,6 +1302,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`.
 
@@ -1310,6 +1326,7 @@ deprecated: v4.0.0
 > Stability: 0 - Deprecated
 
 * `object` {any}
+* Returns: {boolean}
 
 Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`.