Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 5 commits into from
Closed

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

wants to merge 5 commits into from

Conversation

kibertoad
Copy link
Contributor

Description of change

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

@nodejs-github-bot 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 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
@@ -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._
Copy link
Member

@Trott Trott Jul 6, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

In other words:

`file`

instead of:

'file'

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -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._
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrapped in the follow-up commit.

@jasnell
Copy link
Member

jasnell commented Jul 6, 2016

LGTM
@nodejs/documentation

@@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

…, the internally opened …?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in the follow-up commit.

@addaleax
Copy link
Member

addaleax commented Jul 9, 2016

LGTM

_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._
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@kibertoad
Copy link
Contributor Author

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

@@ -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._
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can remove automatically

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?..

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kibertoad
Copy link
Contributor Author

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

@addaleax
Copy link
Member

addaleax commented Aug 4, 2016

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

@addaleax
Copy link
Member

addaleax commented Aug 8, 2016

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

Sorry again this took so long!

@addaleax addaleax closed this Aug 8, 2016
addaleax pushed a commit that referenced this pull request Aug 8, 2016
Ref: #7560
PR-URL: #7561
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
@cjihrig cjihrig mentioned this pull request Aug 8, 2016
@kibertoad
Copy link
Contributor Author

@addaleax np, and thank you!

cjihrig pushed a commit that referenced this pull request Aug 10, 2016
Ref: #7560
PR-URL: #7561
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
@cjihrig cjihrig mentioned this pull request Aug 11, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants