From 351d9dfae45c04fec8ae7dfeac109cb98764752c Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Wed, 17 Oct 2018 12:56:13 +0530
Subject: [PATCH 1/7] doc: clarify fd behaviour with {read,write}File

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

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b3af66364b1cbb..2a01de812f20ee 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2547,10 +2547,13 @@ fs.readFile('<directory>', (err, data) => {
 });
 ```
 
-Any specified file descriptor has to support reading.
-
-If a file descriptor is specified as the `path`, it will not be closed
+### File Descriptors
+1. Any specified file descriptor has to support reading.
+2. If a file descriptor is specified as the `path`, it will not be closed
 automatically.
+3. The reading will begin at the current position. If the file size is
+10 bytes and if six bytes are already read with this file descriptor, then
+`readFile` will return only the rest of the four bytes.
 
 The `fs.readFile()` function buffers the entire file. To minimize memory costs,
 when possible prefer streaming via `fs.createReadStream()`.
@@ -3540,14 +3543,21 @@ If `options` is a string, then it specifies the encoding:
 fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
 ```
 
-Any specified file descriptor has to support writing.
+### File Descriptors
+1. Any specified file descriptor has to support writing.
+2. If a file descriptor is specified as the `file`, it will not be closed
+automatically.
+3. The writing will begin at the beginning of the file. If the file size
+is 10 bytes and if six bytes are written with this file descriptor, then
+`writeFile` will return six bytes newly written and four bytes from the file.
+For example, if the file already had `'Hello World'` and the newly written
+content is `'Aloha'`, then the contents of the file would be `'Aloha World'`,
+rather than just `'Aloha'`.
 
 It is unsafe to use `fs.writeFile()` multiple times on the same file without
 waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
 recommended.
 
-If a file descriptor is specified as the `file`, it will not be closed
-automatically.
 
 ## fs.writeFileSync(file, data[, options])
 <!-- YAML

From 5370c1482ad7c8a5431f3e818574d3ae74e391c7 Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Fri, 19 Oct 2018 14:48:46 +0530
Subject: [PATCH 2/7] address @vsemozhetbyt's comments

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

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 2a01de812f20ee..9c9ae0c25fea61 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2553,7 +2553,7 @@ fs.readFile('<directory>', (err, data) => {
 automatically.
 3. The reading will begin at the current position. If the file size is
 10 bytes and if six bytes are already read with this file descriptor, then
-`readFile` will return only the rest of the four bytes.
+`readFile()` will return only the rest of the four bytes.
 
 The `fs.readFile()` function buffers the entire file. To minimize memory costs,
 when possible prefer streaming via `fs.createReadStream()`.
@@ -3547,12 +3547,12 @@ fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
 1. Any specified file descriptor has to support writing.
 2. If a file descriptor is specified as the `file`, it will not be closed
 automatically.
-3. The writing will begin at the beginning of the file. If the file size
-is 10 bytes and if six bytes are written with this file descriptor, then
-`writeFile` will return six bytes newly written and four bytes from the file.
-For example, if the file already had `'Hello World'` and the newly written
-content is `'Aloha'`, then the contents of the file would be `'Aloha World'`,
-rather than just `'Aloha'`.
+3. The writing will begin at the beginning of the file. If the file size is 10
+bytes and if six bytes are written with this file descriptor, then the file
+contents would be six newly written bytes and four bytes which were already
+there in the file from position seven to ten. For example, if the file already
+had `'Hello World'` and the newly written content is `'Aloha'`, then the
+contents of the file would be `'Aloha World'`, rather than just `'Aloha'`.
 
 It is unsafe to use `fs.writeFile()` multiple times on the same file without
 waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is

From b5a440c19119014b5f4f09ffdf702fcc739d905b Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Sat, 20 Oct 2018 04:21:03 +0530
Subject: [PATCH 3/7] changes because of #23709

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

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 9c9ae0c25fea61..ee234ad3156d57 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3547,12 +3547,23 @@ fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
 1. Any specified file descriptor has to support writing.
 2. If a file descriptor is specified as the `file`, it will not be closed
 automatically.
-3. The writing will begin at the beginning of the file. If the file size is 10
-bytes and if six bytes are written with this file descriptor, then the file
-contents would be six newly written bytes and four bytes which were already
-there in the file from position seven to ten. For example, if the file already
-had `'Hello World'` and the newly written content is `'Aloha'`, then the
-contents of the file would be `'Aloha World'`, rather than just `'Aloha'`.
+3. The writing will begin at the current position. Basically, if there are
+multiple write calls to a file descriptor and then a `writeFile()` call is
+made with the same file descriptor, the data would have been appended.
+For example, if we did something like this
+```js
+fs.writeFile(fd, 'Hello', function(err) {
+  if (err) {
+    throw err;
+  }
+  fs.writeFile(fd, 'World', function(err) {
+    if (err) {
+      throw err;
+    }
+    // At this point, file will have `HelloWorld`.
+  });
+});
+```
 
 It is unsafe to use `fs.writeFile()` multiple times on the same file without
 waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is

From d44bf9fc8cce351afcd5edc5eca635d9d022b9c1 Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Sat, 20 Oct 2018 04:23:53 +0530
Subject: [PATCH 4/7] group the relevant parts

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

diff --git a/doc/api/fs.md b/doc/api/fs.md
index ee234ad3156d57..fa389416e834cd 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2547,6 +2547,9 @@ fs.readFile('<directory>', (err, data) => {
 });
 ```
 
+The `fs.readFile()` function buffers the entire file. To minimize memory costs,
+when possible prefer streaming via `fs.createReadStream()`.
+
 ### File Descriptors
 1. Any specified file descriptor has to support reading.
 2. If a file descriptor is specified as the `path`, it will not be closed
@@ -2555,9 +2558,6 @@ automatically.
 10 bytes and if six bytes are already read with this file descriptor, then
 `readFile()` will return only the rest of the four bytes.
 
-The `fs.readFile()` function buffers the entire file. To minimize memory costs,
-when possible prefer streaming via `fs.createReadStream()`.
-
 ## fs.readFileSync(path[, options])
 <!-- YAML
 added: v0.1.8
@@ -3543,6 +3543,10 @@ If `options` is a string, then it specifies the encoding:
 fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
 ```
 
+It is unsafe to use `fs.writeFile()` multiple times on the same file without
+waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
+recommended.
+
 ### File Descriptors
 1. Any specified file descriptor has to support writing.
 2. If a file descriptor is specified as the `file`, it will not be closed
@@ -3565,10 +3569,6 @@ fs.writeFile(fd, 'Hello', function(err) {
 });
 ```
 
-It is unsafe to use `fs.writeFile()` multiple times on the same file without
-waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
-recommended.
-
 
 ## fs.writeFileSync(file, data[, options])
 <!-- YAML

From 121e1dd077745278f93ec297aa9b58cf690ea57a Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Sat, 20 Oct 2018 04:30:52 +0530
Subject: [PATCH 5/7] update fs promisified functions' behaviour

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

diff --git a/doc/api/fs.md b/doc/api/fs.md
index fa389416e834cd..ffcec1fc86e4f5 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3801,6 +3801,11 @@ returned.
 
 The `FileHandle` has to support reading.
 
+**Note:** If one or more `filehandle.read()` calls are made on a file handle
+and then a `filehandle.readFile()` call is made, the data will be read from
+the current position till the end of the file. It doesn't always read from the
+beginning of the file.
+
 #### filehandle.stat([options])
 <!-- YAML
 added: v10.0.0
@@ -3963,6 +3968,11 @@ The `FileHandle` has to support writing.
 It is unsafe to use `filehandle.writeFile()` multiple times on the same file
 without waiting for the `Promise` to be resolved (or rejected).
 
+**Note:** If one or more `filehandle.write()` calls are made on a file handle
+and then a `filehandle.writeFile()` call is made, the data will be written from
+the current position till the end of the file. It doesn't always write from the
+beginning of the file.
+
 ### fsPromises.access(path[, mode])
 <!-- YAML
 added: v10.0.0

From 9975e9ae064a39443c8c5be9b5b6e44e22647824 Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Wed, 24 Oct 2018 18:36:10 +0530
Subject: [PATCH 6/7] Revert "changes because of #23709"

This reverts commit b5a440c19119014b5f4f09ffdf702fcc739d905b.
---
 doc/api/fs.md | 23 ++++++-----------------
 1 file changed, 6 insertions(+), 17 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index ffcec1fc86e4f5..b63bc506184119 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3551,23 +3551,12 @@ recommended.
 1. Any specified file descriptor has to support writing.
 2. If a file descriptor is specified as the `file`, it will not be closed
 automatically.
-3. The writing will begin at the current position. Basically, if there are
-multiple write calls to a file descriptor and then a `writeFile()` call is
-made with the same file descriptor, the data would have been appended.
-For example, if we did something like this
-```js
-fs.writeFile(fd, 'Hello', function(err) {
-  if (err) {
-    throw err;
-  }
-  fs.writeFile(fd, 'World', function(err) {
-    if (err) {
-      throw err;
-    }
-    // At this point, file will have `HelloWorld`.
-  });
-});
-```
+3. The writing will begin at the beginning of the file. If the file size is 10
+bytes and if six bytes are written with this file descriptor, then the file
+contents would be six newly written bytes and four bytes which were already
+there in the file from position seven to ten. For example, if the file already
+had `'Hello World'` and the newly written content is `'Aloha'`, then the
+contents of the file would be `'Aloha World'`, rather than just `'Aloha'`.
 
 
 ## fs.writeFileSync(file, data[, options])

From ef290a78d8fbddf0b870c27f60235a5e88635aac Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Wed, 24 Oct 2018 18:48:49 +0530
Subject: [PATCH 7/7] address review comments

---
 doc/api/fs.md | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b63bc506184119..59a971c97b8d6a 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2554,9 +2554,10 @@ when possible prefer streaming via `fs.createReadStream()`.
 1. Any specified file descriptor has to support reading.
 2. If a file descriptor is specified as the `path`, it will not be closed
 automatically.
-3. The reading will begin at the current position. If the file size is
-10 bytes and if six bytes are already read with this file descriptor, then
-`readFile()` will return only the rest of the four bytes.
+3. The reading will begin at the current position. For example, if the file
+already had `'Hello World`' and six bytes are read with the file descriptor,
+the call to `fs.readFile()` with the same file descriptor, would give
+`'World'`, rather than `'Hello World'`.
 
 ## fs.readFileSync(path[, options])
 <!-- YAML
@@ -3551,12 +3552,10 @@ recommended.
 1. Any specified file descriptor has to support writing.
 2. If a file descriptor is specified as the `file`, it will not be closed
 automatically.
-3. The writing will begin at the beginning of the file. If the file size is 10
-bytes and if six bytes are written with this file descriptor, then the file
-contents would be six newly written bytes and four bytes which were already
-there in the file from position seven to ten. For example, if the file already
-had `'Hello World'` and the newly written content is `'Aloha'`, then the
-contents of the file would be `'Aloha World'`, rather than just `'Aloha'`.
+3. The writing will begin at the beginning of the file. For example, if the
+file already had `'Hello World'` and the newly written content is `'Aloha'`,
+then the contents of the file would be `'Aloha World'`, rather than just
+`'Aloha'`.
 
 
 ## fs.writeFileSync(file, data[, options])
@@ -3790,10 +3789,10 @@ returned.
 
 The `FileHandle` has to support reading.
 
-**Note:** If one or more `filehandle.read()` calls are made on a file handle
-and then a `filehandle.readFile()` call is made, the data will be read from
-the current position till the end of the file. It doesn't always read from the
-beginning of the file.
+If one or more `filehandle.read()` calls are made on a file handle and then a
+`filehandle.readFile()` call is made, the data will be read from the current
+position till the end of the file. It doesn't always read from the beginning
+of the file.
 
 #### filehandle.stat([options])
 <!-- YAML
@@ -3957,9 +3956,9 @@ The `FileHandle` has to support writing.
 It is unsafe to use `filehandle.writeFile()` multiple times on the same file
 without waiting for the `Promise` to be resolved (or rejected).
 
-**Note:** If one or more `filehandle.write()` calls are made on a file handle
-and then a `filehandle.writeFile()` call is made, the data will be written from
-the current position till the end of the file. It doesn't always write from the
+If one or more `filehandle.write()` calls are made on a file handle and then a
+`filehandle.writeFile()` call is made, the data will be written from the
+current position till the end of the file. It doesn't always write from the
 beginning of the file.
 
 ### fsPromises.access(path[, mode])