doc: synchronize argument names for appendFile() by Trott · Pull Request #20489 · nodejs/node
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.
added
doc
labels
May 3, 2018
vsemozhetbyt
added
fast-track
labels
May 3, 2018Trott added a commit to Trott/io.js that referenced this pull request
May 3, 2018The 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 <vsemozhetbyt@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
MylesBorins pushed a commit that referenced this pull request
May 4, 2018The 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 <vsemozhetbyt@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Trott
mentioned this pull request
4 tasks
MylesBorins pushed a commit that referenced this pull request
May 8, 2018The 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 <vsemozhetbyt@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Trott
deleted the
pathpathpath
branch
This file contains hidden or 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