Multiple Documentation Issues in fs and fs/promises Modules (Formatting, Consistency, and Clarity) #60280
Description
Affected URL(s)
https://nodejs.org/api/fs.html#filehandlewritebuffer-offset-length-position, https://nodejs.org/api/fs.html#fsreadfd-buffer-offset-length-position-callback, https://nodejs.org/api/fs.html#fsmkdirpath-options-callback, https://nodejs.org/api/fs.html#fsrmdirpath-options-callback, https://nodejs.org/api/fs.html#fschmodpath-mode-callback, https://nodejs.org/api/fs.html#fsreadfilepath-options-callback
Description of the problem
Summary
While reviewing the fs and fs/promises documentation, I found several small but important documentation issues related to formatting, consistency, and missing clarifications. These are not code bugs — only documentation fixes.
1. Formatting Error in filehandle.write()
Current: Default:pwrite(2)null
Expected: Default: null (See pwrite(2))
→ Markdown rendering error; link and default value merged together.
2. Inconsistent Default Formatting
Some parameters show Default::null (double colon) instead of Default: null.
Occurs in multiple methods across fs.
3. Missing EOF Clarification in fs.read()
bytesRead can be 0 to indicate end-of-file, but this is not stated in the parameter description — only implied later in text.
4. Ambiguous Deprecation for recursive Option
In fs.rmdir() and fs.mkdir(), the recursive option is marked as Deprecated, but:
- No version is mentioned
- No alternative (
fs.rm()/fs.mkdir({ recursive: true })) is provided - No note if it’s still safe to use
5. Missing Cross-Link for File Modes
The “File modes” table appears only under fs.chmod() but applies to multiple APIs like fs.open(), fs.mkdir(), etc.
Suggestion: Add “See also: File modes” links in related methods.
6. Performance Warning Placement in fs.readFile()
Performance warning about reading large files is buried at the end after examples.
Suggestion: Move it higher or highlight as “
All these are low-risk, documentation-only improvements that enhance clarity and developer experience.
I’m happy to submit PRs if needed.