doc: synchronize argument names for appendFile() #20489
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The documentation used `file` for the first argument to `appendFile()` functions. However, the code and (more importantly) thrown errors referred to it as `path`. The latter is especially important because context is not provided. So you're looking for a function that takes `path` but that string doesn't appear in your code *or* in the documentation. It's not until the end user looks at the source code of Node.js that they can figure out what's going on. This is why it is important that the names of variables in the documentation match that in the code. If we want to change this to `file`, then that's OK, but we need to do it in the source code and error messages too, not just in the docs. Changing the docs is the smallest change to synchronize everything so that's what this change does.
nodejs-github-bot
added
doc
|
Why this matters: $ node
> fs.appendFile(undefined, 'foo', () => {})
TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be one of type string, Buffer, or URL. Received type undefined
at Object.fs.open (fs.js:523:3)
at Object.fs.writeFile (fs.js:1253:6)
at Object.fs.appendFile (fs.js:1308:6)
>The error message refers to it as the "path" argument. So the documentation should do the same or else things are puzzling for the user until they look at the source code for Node.js. |
vsemozhetbyt
approved these changes
May 3, 2018
|
Node.js Collaborators, please, add 👍 here if you approve fast-tracking. |
vsemozhetbyt
added
fast-track
trivikr
approved these changes
May 3, 2018
|
Landed in a00f76c |
Trott
added a commit
to Trott/io.js
that referenced
this pull request
May 3, 2018
The documentation used `file` for the first argument to `appendFile()` functions. However, the code and (more importantly) thrown errors referred to it as `path`. The latter is especially important because context is not provided. So you're looking for a function that takes `path` but that string doesn't appear in your code *or* in the documentation. It's not until the end user looks at the source code of Node.js that they can figure out what's going on. This is why it is important that the names of variables in the documentation match that in the code. If we want to change this to `file`, then that's OK, but we need to do it in the source code and error messages too, not just in the docs. Changing the docs is the smallest change to synchronize everything so that's what this change does. PR-URL: nodejs#20489 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
MylesBorins
pushed a commit
that referenced
this pull request
May 4, 2018
The documentation used `file` for the first argument to `appendFile()` functions. However, the code and (more importantly) thrown errors referred to it as `path`. The latter is especially important because context is not provided. So you're looking for a function that takes `path` but that string doesn't appear in your code *or* in the documentation. It's not until the end user looks at the source code of Node.js that they can figure out what's going on. This is why it is important that the names of variables in the documentation match that in the code. If we want to change this to `file`, then that's OK, but we need to do it in the source code and error messages too, not just in the docs. Changing the docs is the smallest change to synchronize everything so that's what this change does. PR-URL: #20489 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
4 tasks
Merged
MylesBorins
pushed a commit
that referenced
this pull request
May 8, 2018
The documentation used `file` for the first argument to `appendFile()` functions. However, the code and (more importantly) thrown errors referred to it as `path`. The latter is especially important because context is not provided. So you're looking for a function that takes `path` but that string doesn't appear in your code *or* in the documentation. It's not until the end user looks at the source code of Node.js that they can figure out what's going on. This is why it is important that the names of variables in the documentation match that in the code. If we want to change this to `file`, then that's OK, but we need to do it in the source code and error messages too, not just in the docs. Changing the docs is the smallest change to synchronize everything so that's what this change does. PR-URL: #20489 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The documentation used
filefor the first argument toappendFile()functions. However, the code and (more importantly) thrown errors
referred to it as
path. The latter is especially important becausecontext is not provided. So you're looking for a function that takes
pathbut that string doesn't appear in your code or in thedocumentation. It's not until the end user looks at the source code of
Node.js that they can figure out what's going on. This is why it is
important that the names of variables in the documentation match that in
the code. If we want to change this to
file, then that's OK, but weneed to do it in the source code and error messages too, not just in the
docs. Changing the docs is the smallest change to synchronize everything
so that's what this change does.
Checklist