From 236281c0e858243c1444d47bf2738516c25375e0 Mon Sep 17 00:00:00 2001
From: Evan Lucas <evanlucas@me.com>
Date: Thu, 14 Dec 2017 05:56:38 -0600
Subject: [PATCH 1/3] doc: improve fs api descriptions

This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.
---
 doc/api/fs.md | 33 ++++++++++++++++++++++++---------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index fb8d246f03d845..101472afab90a7 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -669,8 +669,10 @@ changes:
 * `callback` {Function}
   * `err` {Error}
 
-Asynchronous chmod(2). No arguments other than a possible exception are given
-to the completion callback.
+Asynchronously changes the mode of a file. No arguments other than a possible
+exception are given to the completion callback.
+
+See also: chmod(2)
 
 ## fs.chmodSync(path, mode)
 <!-- YAML
@@ -685,7 +687,9 @@ changes:
 * `path` {string|Buffer|URL}
 * `mode` {integer}
 
-Synchronous chmod(2). Returns `undefined`.
+The synchronous version of [`fs.chmod()`][]. Returns `undefined`.
+
+See also: chmod(2)
 
 ## fs.chown(path, uid, gid, callback)
 <!-- YAML
@@ -707,8 +711,10 @@ changes:
 * `callback` {Function}
   * `err` {Error}
 
-Asynchronous chown(2). No arguments other than a possible exception are given
-to the completion callback.
+Asynchronously changes owner and group of a file. No arguments other than a
+possible exception are given to the completion callback.
+
+See also: chown(2)
 
 ## fs.chownSync(path, uid, gid)
 <!-- YAML
@@ -724,7 +730,9 @@ changes:
 * `uid` {integer}
 * `gid` {integer}
 
-Synchronous chown(2). Returns `undefined`.
+Synchronous version of [`fs.chown()`][]. Returns `undefined`.
+
+See also: chown(2)
 
 ## fs.close(fd, callback)
 <!-- YAML
@@ -1511,8 +1519,10 @@ changes:
 * `callback` {Function}
   * `err` {Error}
 
-Asynchronous mkdir(2). No arguments other than a possible exception are given
-to the completion callback. `mode` defaults to `0o777`.
+Asynchronously creates a directory. No arguments other than a possible exception
+are given to the completion callback. `mode` defaults to `0o777`.
+
+See also: mkdir(2)
 
 ## fs.mkdirSync(path[, mode])
 <!-- YAML
@@ -1527,7 +1537,9 @@ changes:
 * `path` {string|Buffer|URL}
 * `mode` {integer} **Default:** `0o777`
 
-Synchronous mkdir(2). Returns `undefined`.
+The synchronous version of [`fs.mkdir()`][]. Returns `undefined`.
+
+See also: mkdir(2)
 
 ## fs.mkdtemp(prefix[, options], callback)
 <!-- YAML
@@ -3103,10 +3115,13 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`fs.Stats`]: #fs_class_fs_stats
 [`fs.access()`]: #fs_fs_access_path_mode_callback
 [`fs.appendFile()`]: fs.html#fs_fs_appendfile_file_data_options_callback
+[`fs.chmod()`]: #fs_fs_chmod_path_mode_callback
+[`fs.chown()`]: #fs_fs_chown_path_uid_gid_callback
 [`fs.exists()`]: fs.html#fs_fs_exists_path_callback
 [`fs.fstat()`]: #fs_fs_fstat_fd_callback
 [`fs.futimes()`]: #fs_fs_futimes_fd_atime_mtime_callback
 [`fs.lstat()`]: #fs_fs_lstat_path_callback
+[`fs.mkdir()`]: #fs_fs_mkdir_path_mode_callback
 [`fs.mkdtemp()`]: #fs_fs_mkdtemp_prefix_options_callback
 [`fs.open()`]: #fs_fs_open_path_flags_mode_callback
 [`fs.read()`]: #fs_fs_read_fd_buffer_offset_length_position_callback

From d01acf2e757e88eee404f23380490b52dce657c3 Mon Sep 17 00:00:00 2001
From: Evan Lucas <evanlucas@me.com>
Date: Thu, 14 Dec 2017 06:11:10 -0600
Subject: [PATCH 2/3] fixup!: change mode to permissions

---
 doc/api/fs.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 101472afab90a7..5aa3b20ce5ed96 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -669,8 +669,8 @@ changes:
 * `callback` {Function}
   * `err` {Error}
 
-Asynchronously changes the mode of a file. No arguments other than a possible
-exception are given to the completion callback.
+Asynchronously changes the permissions of a file. No arguments other than a
+possible exception are given to the completion callback.
 
 See also: chmod(2)
 

From c2c6509f5f8f946080e8acd9359790b3c42b0b4c Mon Sep 17 00:00:00 2001
From: Evan Lucas <evanlucas@me.com>
Date: Mon, 18 Dec 2017 14:26:29 -0600
Subject: [PATCH 3/3] fixup!: improve text

---
 doc/api/fs.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 5aa3b20ce5ed96..c623694393e5de 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -687,7 +687,8 @@ changes:
 * `path` {string|Buffer|URL}
 * `mode` {integer}
 
-The synchronous version of [`fs.chmod()`][]. Returns `undefined`.
+Synchronously changes the permissions of a file. Returns `undefined`.
+This is the synchronous version of [`fs.chmod()`][].
 
 See also: chmod(2)
 
@@ -730,7 +731,8 @@ changes:
 * `uid` {integer}
 * `gid` {integer}
 
-Synchronous version of [`fs.chown()`][]. Returns `undefined`.
+Synchronously changes owner and group of a file. Returns `undefined`.
+This is the synchronous version of [`fs.chown()`][].
 
 See also: chown(2)
 
@@ -1537,7 +1539,8 @@ changes:
 * `path` {string|Buffer|URL}
 * `mode` {integer} **Default:** `0o777`
 
-The synchronous version of [`fs.mkdir()`][]. Returns `undefined`.
+Synchronously creates a directory. Returns `undefined`.
+This is the synchronous version of [`fs.mkdir()`][]. 
 
 See also: mkdir(2)