Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… #7561

kibertoad · 2016-07-06T12:15:00Z

Description of change

"fs.readFile", "fs.appendFile", "fs.writeFile" documentation is made less confusing regarding when does the automatic closing of file descriptors occur.

…umentation regarding closing.

Trott · 2016-07-06T13:58:48Z

doc/api/fs.md

@@ -378,7 +378,9 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);

 Any specified file descriptor has to have been opened for appending.

-_Note: Specified file descriptors will not be closed automatically._
+_Note: If a file descriptor is specified as the 'file', it will not be closed automatically._


Please use backticks instead of single quotes around file here and in the other notes.

In other words:

`file`

instead of:

'file'

Thanks for the feedback, replaced with the backticks in the new commit.

jasnell · 2016-07-06T15:06:50Z

doc/api/fs.md

@@ -378,7 +378,9 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);

 Any specified file descriptor has to have been opened for appending.

-_Note: Specified file descriptors will not be closed automatically._
+_Note: If a file descriptor is specified as the `file`, it will not be closed automatically._


Can you please line wrap at no longer than 80-chars

Wrapped in the follow-up commit.

jasnell · 2016-07-06T23:49:10Z

LGTM
@nodejs/documentation

addaleax · 2016-07-09T22:26:20Z

doc/api/fs.md

@@ -1130,7 +1132,9 @@ fs.readFile('/etc/passwd', 'utf8', callback);

 Any specified file descriptor has to support reading.

-_Note: Specified file descriptors will not be closed automatically._
+_Note: If a file descriptor is specified as the `file`, it will not be closed 
+automatically. If a filename is specified as the `file`, internally opened 


…, the internally opened …?

Fixed in the follow-up commit.

addaleax · 2016-07-09T22:39:24Z

LGTM

thefourtheye · 2016-07-10T07:16:24Z

doc/api/fs.md

-_Note: Specified file descriptors will not be closed automatically._
+_Note: If a file descriptor is specified as the `file`, it will not be closed 
+automatically. If a filename is specified as the `file`, the internally opened 
+file descriptor will be closed automatically._


If the same text has to be repeated multiple times, wouldn't it be better to have it as a separate section and link it wherever necessary?

It's not such a long text and it didn't bother anyone about the original text. Wouldn't it unnecessarily complicate things? Are there any existing precedents of similar treatment of three-liners?

Btw, while that second sentence is true, I’m not sure it’s actually relevant; that writing to a file based on its name includes opening and closing a file descriptor seems like an implementation detail to me which the user doesn’t need to know anything about.

Fair enough. Do you think that the second sentence should be removed altogether? I'm not entirely sure there is no value in explicitly telling the user that he doesn't need to worry about releasing resources in some of the use cases (as opposed to another documented case when he, indeed, should worry), but if you think that it's already implied in a clear enough way in the first sentence, I'm fine with dropping it.

I’d be pretty fine with dropping it, too. The first sentence seems clear enough to me.

kibertoad · 2016-07-17T23:33:22Z

OK, removed the excessive second part. Anything else?..

thefourtheye · 2016-07-18T13:03:56Z

doc/api/fs.md

@@ -378,7 +378,8 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);

 Any specified file descriptor has to have been opened for appending.

-_Note: Specified file descriptors will not be closed automatically._
+_Note: If a file descriptor is specified as the `file`, it will not be closed 
+automatically._


I think we can remove automatically

It was in the original text. It makes perfect sense. It's just one word and doesn't overload text or can be a source of confusion. Why does it have to be removed?..

I’m +1 on keeping it, too. The file descriptor obviously should be closed at some point, that just doesn’t happen by calling {append,read,write}File.

Does that mean that this PR is finally in a proper shape :)?

That’s what my “LGTM” (= looks good to me) basically says, yes. :) It’s still part of the process of merging PRs that collaborators have the chance to state their opinion on changes, like @thefourtheye did, and discuss them if necessary.

Also, you could do us a favour by squashing the commits here together and formatting the commit message as requested by the CONTRIBUTING.md (that’s also something that can be done by the person landing this PR).

ping @thefourtheye?

kibertoad · 2016-07-19T22:01:07Z

Bump to get more feedback on latest suggestion (seriously, how does any documentation change ever gets merged?..)

addaleax · 2016-08-04T23:56:03Z

Ok, sorry it’s taking so long, I’ll land this by Monday in its current state if there are no objections.

addaleax · 2016-08-08T13:28:03Z

Landed in beea23a with the commit message modified to fit the contributing.md format.

Sorry again this took so long!

Ref: #7560 PR-URL: #7561 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

kibertoad · 2016-08-10T09:35:11Z

@addaleax np, and thank you!

Ref: #7560 PR-URL: #7561 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

refs #7560 Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc…

e4a8d56

…umentation regarding closing.

nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Jul 6, 2016

kibertoad changed the title ~~refs #7560 Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc…~~ Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… Jul 6, 2016

kibertoad mentioned this pull request Jul 6, 2016

Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" documentation regarding closing #7560

Closed

Trott reviewed Jul 6, 2016
View reviewed changes

refs #7560 Use backticks instead of single quotes.

a851058

jasnell reviewed Jul 6, 2016
View reviewed changes

refs #7560 Merge two notes, wrap at 80 symbols.

40a5750

addaleax reviewed Jul 9, 2016
View reviewed changes

refs #7560 Add missing "the".

7e617e0

thefourtheye reviewed Jul 10, 2016
View reviewed changes

refs #7560 Removed excessive detail about internal implementation.

b5baaa2

thefourtheye reviewed Jul 18, 2016
View reviewed changes

addaleax closed this Aug 8, 2016

addaleax pushed a commit that referenced this pull request Aug 8, 2016

doc: clarify fd closing by fs.readFile etc.

beea23a

Ref: #7560 PR-URL: #7561 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

cjihrig mentioned this pull request Aug 8, 2016

v6.4.0 Release Proposal #8020

Closed

cjihrig pushed a commit that referenced this pull request Aug 10, 2016

doc: clarify fd closing by fs.readFile etc.

dedfcb7

Ref: #7560 PR-URL: #7561 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

cjihrig mentioned this pull request Aug 11, 2016

v6.4.0 Proposal #8070

Merged

MylesBorins added the dont-land-on-v4.x label Sep 30, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… #7561

Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… #7561

kibertoad commented Jul 6, 2016

Trott Jul 6, 2016 •

edited

Loading

kibertoad Jul 6, 2016

jasnell Jul 6, 2016

kibertoad Jul 6, 2016

jasnell commented Jul 6, 2016

addaleax Jul 9, 2016

kibertoad Jul 9, 2016

addaleax commented Jul 9, 2016

thefourtheye Jul 10, 2016

kibertoad Jul 10, 2016

addaleax Jul 15, 2016

kibertoad Jul 15, 2016

addaleax Jul 15, 2016

kibertoad commented Jul 17, 2016

thefourtheye Jul 18, 2016

kibertoad Jul 19, 2016

addaleax Jul 19, 2016

kibertoad Jul 19, 2016

addaleax Jul 19, 2016

addaleax Jul 26, 2016

kibertoad commented Jul 19, 2016

addaleax commented Aug 4, 2016

addaleax commented Aug 8, 2016

kibertoad commented Aug 10, 2016

Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… #7561

Clarify "fs.readFile", "fs.appendFile", "fs.writeFile" doc… #7561

Conversation

kibertoad commented Jul 6, 2016

Description of change

Trott Jul 6, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Jul 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addaleax commented Jul 9, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibertoad commented Jul 17, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibertoad commented Jul 19, 2016

addaleax commented Aug 4, 2016

addaleax commented Aug 8, 2016

kibertoad commented Aug 10, 2016

Trott Jul 6, 2016 •

edited

Loading