Repository navigation
readdir docs don’t mention when options argument was added #12299
Description
fs.readdir(path[, options], callback)
History
Version Changes v7.0.0 The callback parameter is no longer optional. Not passing it will emit a deprecation warning. v0.1.8 Added in: v0.1.8
options was added in Node 6.0.0 by #5616. But it’s not mentioned, which led me to writing generic code that passed through undefined for options, which naturally made it fall apart on the Node 4 LTS release that doesn’t support options and so perceived it as just an undefined callback.
This really worries me. If something like this can change without any note in the history, what else is lacking history of changes that will come and bite me later? I no longer trust this documentation. At least https://nodejs.org/docs/latest-v4.x/api/fs.html#fs_fs_readdir_path_callback is still there, I’ll just need to remember to work there.
Activity
joyeecheung commentedon Apr 10, 2017
The per-item changes in the documentation is added in #11489, which happened much later than the v6.0.0 release, so it's very likely there would be something falling through the cracks. The differences between v4 and v6 are also documented in
https://github.com/nodejs/node/wiki/Breaking-changes-between-v4-LTS-and-v6-LTS.
I agree the missing documentation for previous changes would confuse users, and it definitely needs improvement, though I believe the documentation would be more reliable in future releases, now that we have a system like this in place.
Labeled as a good first contribution, feel free to open a PR to fix this!
(Also, maybe we can open a meta issue to hunt for more missing changelog items? Should not be that hard if we go through the semver-major PRs)
gibfahn commentedon Apr 10, 2017
We'd have to look at semver-minor PRs as well (and check whether/how far they got backported).
shubheksha commentedon Apr 10, 2017
I'll take this up!
doc: add missing changelog entry for fs.readdir()
doc: add missing changelog entry for fs.readdir()
doc: add missing changelog entry for fs.readdir()
doc: add missing changelog entry for fs.readdir()