Documentation for "path", "bytesRead", "bytesWritten" properties should also be in stream.html, not just fs.html

[lll000111]

Relating to #4327 and #4368

I just searched and searched and had to resort to various tricky Google queries to find that the path property of stream(!) objects is not documented on the "stream" doc page - but on the "fs" page.

https://nodejs.org/dist/latest-v8.x/docs/api/fs.html#fs_writestream_path

I think this belongs to https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_class_stream_writable and https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_class_stream_readable (too)

On that note, I find it highly confusing that there is a class fs.WriteStream (same for ReadStream) documented. Sure, it says "is a WriteStream", but combined with the fact that the documentation is DIFFERENT for the class on the two pages leads to the assumption that maybe it indeed is something different? I had to check the code in lib/fs.js to make sure it really is the same class.

So maybe there should be only one location for stream class documentation - and that should be under "streams"?

[addaleax]

I just searched and searched and had to resort to various tricky Google queries to find that the path property of stream(!) objects is not documented on the "stream" doc page - but on the "fs" page.

Yes, that’s because non-fs streams don’t have that property (for example, sockets).

I find it highly confusing that there is a class fs.WriteStream (same for ReadStream) documented. Sure, it says "is a WriteStream", but combined with the fact that the documentation is DIFFERENT for the class on the two pages leads to the assumption that maybe it indeed is something different? I had to check the code in lib/fs.js to make sure it really is the same class.

Yes, fs.WriteStream and stream.Writable are different things – fs.WriteStream is a subclass of stream.Writable.

[lll000111]

Okay, some confusion (here). We have a WriteStream and a WriteStream. The entries for both (read/write) streams on the "fs" page say

ReadStream is a Readable Stream.

and

WriteStream is a Writable Stream.

pointing to the stream page. So they are not, really. If I understand you correctly, they are based on ("extends") those streams but have the mentioned additional properties? I'm looking at their code now, but I'd say the documentation could be slightly more clear.

---

I'm also just found that the documentation for fs.WriteStream and fs.ReadStream shows two events close and open . But close as an event is defined on stream$Writable already (has it been overwritten?) , and what is actually meant is a new method close available on fs.WriteStream and fs.ReadStream? Which I found in the Flow library definitions for "node.js/fs" and then found in lib/fs.js as ReadStream.prototype.close = .... (later also copied to WriteStream).

After checking write-stream docs in both "fs" and "stream" and also the code a little bit I'm not sure how I should end a file write stream: Call the end method it got from "stream", or call the close method it got from "fs"?

The example for a file write stream(!) actually is in "streams":
https://nodejs.org/api/stream.html#stream_writable_end_chunk_encoding_callback

So what is the close method for? Ist it purely internal? It doesn't have a "_" in front like the other internal functions (and why did the Flow lib.def. authors pick it up as official method - but that's another question).

[ghost]

Okay, some confusion (here). We have a WriteStream and a WriteStream.

No, the types are:

• stream.WritableStream and fs.WriteStream (note the name difference, Writable vs Write)
• stream.ReadableStream and fs.ReadStream (note the name difference, Readable vs Read)

The documentation is correct.

[lll000111]

The documentation is confusing. Also, what I wrote - a bit more than half a sentence.

I'll unsubscribe, I said what I had to say - the path forward does not look like it's going to be a fruitful and/or useful discussion.

[ghost]

This issue asks to add members of filesystem streams to their parent types in the documentation. This is not the case in the implementation, therefore would be incorrect to do.

The stream types in the stream module (e.g: Readable, Writable, Duplex and Transform) are abstract types, that can be extended to implement a concrete stream type. There are many examples of this in node itself (e.g: http.IncomingMessage extends stream.Readable).

In OOP, the able suffix usually hints the type is an abstract type or interface.

I quite honestly do not see the confusion here. However, a link could help making this clearer.

e.g:

-- ReadStream is a Readable Stream
++ fs.ReadStream is a stream.Readable

Possibly with links to make it easier to navigate.

[apapirovski]

I don't think there's anything confusing here and no one has really volunteered to make this change in over 6 months. Closing but feel free to re-open if you're submitting a PR to change it.