doc: Change doc on fs.rename api w.r.t to windows behaviour

[antsmartian]

Fixes : #21957

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[vsemozhetbyt]

Is the deletion of the last sentence intended?

[vsemozhetbyt]

Linter nit: this line needs to be wrapped to not exceed 80 characters.

[BridgeAR]

As described in ##21957 (comment) that is actually not always true. Unix systems will not raise an exception if the directory is empty. That is only the case for Windows. I did not check but that should hold true for all OS.

[vsemozhetbyt]

Is this true for all supported systems?

[daliadefelipee]

Hi @vsemozhetbyt , actually I think the issue was that the result differs from system to system so I think It wold be nice if the docs inform you about each case, although I don't know if it's possible.

[antsmartian]

I thought of writing like:

Asynchronously rename file or directory at oldPath to the pathname provided
as newPath. In the case that newPath already exists, it will
be overwritten. fs.rename can throw the below error:

• On Linux when renaming directory exists and is NOT empty, it throws a
  ENOTEMPTY error.
• On Unix when renaming directory exists and is NOT empty, it throws a
  ENOENT error.
• On Windows regardless of renaming directory is empty, it throws a
  EPERM error.

No arguments other than a possible exception (like mentioned above) are given to
the completion callback.

Thoughts? cc @vsemozhetbyt@BridgeAR

[antsmartian]

ping @vsemozhetbyt :)

[vsemozhetbyt]

1. Not sure if renaming is a right form here and below. Let's see what native speakers think.
2. a `ENOTEMPTY` - > an `ENOTEMPTY` (as well as below).

[sam-github]

Its not clear or grammatical, call it after the name of the arg: "if newPath exists"... and likewise in other places.

[vsemozhetbyt]

Unfortunately, I have not enough knowledge in this realm to fully review. Maybe @nodejs/fs can assess?

[joyeecheung]

To be honest I feel like this inconsistency is a bug that we need to fix rather than document..

[jasnell]

What's the status on this one?

[antsmartian]

@jasnell I guess doc is fine (until bug fix), but @joyeecheung feels we need to fix. So need input from them.

[antsmartian]

@joyeecheung If there is any plan to fix the actual issue? (Since we discussed documentation wouldn't help much here)

[thefourtheye]

If I am not wrong, this has to be addressed at libuv level. I'll take a look at it and update within this week.

[sam-github]

This just repeats line 2698 in a more complex written form, and it adds confusion. It says an exception is given to the completion callback, but it is an error that is given. Also, more errors than the few documented can occur, and the sentence reads to me as saying that only the errors documented above can be passed. Better, I think, to remove the sentence.

[antsmartian]

@sam-github Make sense.

[cjihrig]

If I am not wrong, this has to be addressed at libuv level.

There was a PR in libuv/libuv#1941, but it didn't really gain any traction.

[thefourtheye]

There was a PR in libuv/libuv#1941, but it didn't really gain any traction.

Awesome we already have some code then. Let's dust it up and reuse 😊

[fhinkel]

Looks like this can be closed. Please re-open if needed.