Node: doc - fs.open does not have an explanation for File Descriptor

[ohimark]

Hello,

There should be an explanation for the File Descriptor _fd_ in this section:
https://nodejs.org/api/fs.html#fs_fs_open_path_flags_mode_callback

_fd_ should have an explanation:
fd: File descriptor. It is a handle/reference to an opened file, used by the read/write methods.

Thank you

[bnoordhuis]

Do we explain what a file system is next? The audience is programmers. Knowledge of basic concepts is assumed.

I checked python's documentation. It mentions file descriptors but doesn't define them either.

[ohimark]

Let's try to calm down _and get down to Earth_ for a second.
The audience of programming languages is everyone. There is no place in which it is written that you need to be part of a certain group, or have prior knowledge of every single aspect of Operating Systems, in order to use a certain programming language.

Remember that we are talking about documentation here. Nothing is assumed, otherwise we wouldn't need documentation. We would just assume that everybody knows how to program in Node.

Additionally, if Python lacks an explanation for what a _fd_ is, then this issue should be reported there as well.

[cjihrig]

I understand your request. The problem with documenting things that aren't specific to Node is that there is no good stopping point. A quick Google search for "file descriptor" turns up a lot of useful results.

[ohimark]

Hello. That's great advice and all, but what is a fd ?

[bnoordhuis]

Nothing is assumed, otherwise we wouldn't need documentation.

Plenty is assumed - floating-point numbers and JSON aren't explained either. If a concept is not specific to node.js, it probably has no place in the docs.

[vsemozhetbyt]

May it be that @ohimark means not that "file descriptor" needs an explanation but that "fd" abbreviation does? It is a pretty common abbreviation, but this can seem a bit bare:

[ohimark]

It seems that there might be differences in our perceptions of good documentation.

In my view, good documentation and implicitly good teachers, do not tell you to go search for the answer somewhere else. They also explain ambiguous two-letter words. They also do not assume anything, so that you don't have to go somewhere else to look for answer. At the very least they provide a link to a source which offers a more comprehensive explanation.

@vsemozhetbyt - You are correct, this should be done at the very least.

[cjihrig]

Defining that fd is a file descriptor seems fine.

[bnoordhuis]

I have no problem with spelling out fd, pull requests welcome, but this...

good documentation [...] do not assume anything

...conflates reference documentation with introductory texts. Both have their place but the docs in this repo are of the first kind, not the second.

[ohimark]

@bnoordhuis This is my opinion and i respect your choice to disagree !

In my view, good documentation and implicitly good teachers, do not tell you to go search for the answer somewhere else.

[evanlucas]

@ohimark would you be interested in submitting a pull request to include a description of fd (both here and elsewhere in the documentation)? Improving the documentation is something I think we should always try to do.

[ohimark]

Yes, i'm currently working on it.

[jasnell]

@ohimark ... Definitely +1 on improving the docs.

[TimothyGu]

fs.open* is an inherently dangerous API because of risks of memory leaks, which can be a very real issue for junior Node.js developers in my offline discussion with @XadillaX a few months ago. My presumption is that not documenting what a file descriptor is would deter people who don't understand the full impact on what it is and does from using it. As a result of that, if we were to document it (which I support), we must put a huge red box there warning users of the potential negative consequences that come with not using it properly.

[bnoordhuis]

Then doesn't it make more sense to have the fs.open() entry steer people to fs.readFile(), fs.createReadStream(), etc? That's going to be more effective than explaining what a file descriptor is. It's already too full of trivia.

memory leaks

Do you mean 'resource leaks'? Barring bugs in node.js itself it can't leak memory.

[bnoordhuis]

This issue has been dormant for over a month so I'll go ahead and close it out. Anyone who feels strongly is welcome to open a pull request.