doc: improvements to fs.markdown copy #4486
Conversation
A major reworking of the fs.markdown structure and text. Moved things around so that they are organized by function, included additional information so there is less of dependency on knowledge of the POSIX API. Other changes: * Documents `.path` on `fs.ReadStream` and `fs.WriteStream` per nodejs#4368 * Include coverage of the file system encoding issue * Example enhancements throughout
jasnell
added
doc
|
Hm, it looks like GH is suppressing the diff, which may make it hard to leave comments. |
|
One note I have off the bat is that the error handling bit at the top might be best handled with a link to the appropriate section of the error handling doc. |
|
This kind of straddles the line between a topic document and a reference document — ideally we'd split this into a "fs" topic doc and a "fs" reference doc, and crosslink between the ref doc and the topic doc. This way we can address questions like "what is a file descriptor and why would I want to manipulate it?" in the topic doc while providing a concise guide for folks who just want to know how to manipulate fds in Node (and, at a broader level, another topic document can address "how do I avoid race conditions" so that this reference doc doesn't have to.) Taking on the structural changes necessary is somewhat blocked by getting a resolution on #4244, though. |
|
@jasnell Is there any way of breaking this up into a couple PRs? I'd like to review, but github won't allow, too many changes. |
|
A thought: could we open a PR to the nodejs/docs repo containing just this file as a single new addition, and do the editing there? |
|
That could work. This one is a beast
|
estliberitas
force-pushed
the
master
branch
2 times, most recently
from
7da4fd4
to
c7066fb
Compare
A major reworking of the fs.markdown structure and text.
Moved things around so that they are organized by function,
included additional information so there is less of dependency
on knowledge of the POSIX API.
Other changes:
.pathonfs.ReadStreamandfs.WriteStreamperdoc: fs - add path property to Write/ReadStream #4368
This one will be difficult to review, and I apologize for that. @nodejs/documentation @bnoordhuis