doc: add a line to specify fs.createWriteStream instance

[zombieleet]

Add a line to specify which fs method to call that returns an instance of fs.WriteStream.
This was specifed in the fs.ReadStream section of the fs documentation

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

-1 The description for fs.createWriteStream() already indicates what type it returns.

[zombieleet]

@mscdex I know about that. There is a line under fs.ReadStream that specifies that fs.createReadStream returns an instance of fs.ReadStream. This is not present under fs.WriteStream

fs.ReadStream
fs.WriteStream

[mscdex]

If anything I'd rather remove the line from the fs.ReadStream description instead.

[addaleax]

I think we should switch the lines around here:

Suggested change

	A successful call to `fs.createWriteStream()` will return a new `fs.WriteStream` object.
	* Extends {stream.Writable}
	* Extends {stream.Writable}
	A successful call to `fs.createWriteStream()` will return a new `fs.WriteStream` object.

To match how it’s done for fs.ReadStream

[addaleax]

-1 The description for fs.createWriteStream() already indicates what type it returns.

@mscdex That comment is not helpful at all, because this is not the documentation for fs.createWriteStream().

[mscdex]

@addaleax It's relevant because it's duplicate information that is already specified in the description for fs.createWriteStream(). Users wouldn't even know to look at the documentation for fs.WriteStream to know that that's the return type of fs.createWriteStream() unless they were casually reading through the entirety of the fs documentation (and even if they were, they would eventually reach the fs.createWriteStream() description anyway).

I also see the removal of the existing wording in the documentation for fs.ReadStream as being a similar change to when we standardized the format for APIs (e.g. when we converted the fs.ReadStream description from freeform text to the * Extends: {...} format when describing its type). In this case we're removing freeform text and relying on the * Returns: {...} information.

[addaleax]

@mscdex Fwiw, classes are listed in the fs table of contents before methods, so if I were to look for a way to write to a file, this would be the first entry I encounter, and at least the deprecations docs also link to methods in the class description and not the method that creates these streams.

[mscdex]

so if I were to look for a way to write to a file, this would be the first entry I encounter

Honestly if users are coming to the API reference documentation to learn how to perform a specific task (e.g. "how to write to a file"), they are probably either going to instead:

• Search google, which would reveal usage of fs.createWriteStream()/fs.writeFile()/etc. at which point they would then refer to the API documentation for that function.
• CTRL-F for 'write' in the API documentation and find a sensibly-named function (fs.createWriteStream()/fs.writeFile()/etc.) that way and read the corresponding description.
• Or look at the examples at the very top of the API documentation page (yes I am aware there is not one there specifically for fs.createWriteStream(), but that's irrelevant).

[addaleax]

@mscdex If that’s the case, I would consider our docs to be insufficient. Yes, they are reference docs, but they are also all the official documentation that exists.

/cc @nodejs/documentation

[jasnell]

Landed alternative 6b2b886