fs.truncate accepts an fd but it's poorly documented

[seishun]

• Version: master
• Platform: all
• Subsystem: fs

As I just found out from #15409, you can call fs.truncate with an fd:

> var fd = fs.openSync('asdf.txt', 'r+')
undefined
> fs.truncateSync(fd)
undefined

But this behavior is surprising, since there's fs.ftruncate for fds and it's easy to overlook the note in the documentation for fs.truncate.

Options:

1. Improve documentation for fs.truncate to make it more obvious that it also takes fds. For instance, path <string> | <Buffer> needs to be replaced with something like pathOrFd <string> | <Buffer> | <number>, and Asynchronous truncate(2). needs to be replaced with something like Asynchronous truncate(2) or ftruncate(2) depending on the argument.
2. Phase out fd support in fs.truncate. This would be my preference, since it would avoid having two functions that can do the same thing, and it would make code such as fs.truncate(f) more readable because it would be obvious that f is a path and not an fd.

[ghost]

@Fishrock123 @mscdex @seishun I'm for option 2.

1. I'll print a deprecation warning in
   if (typeof path === 'number') { return fs.ftruncate(path, len, callback); }

2. Remove from docs in ftruncate,
   A file descriptor can also be passed as the first argument. In this case, fs.ftruncate() is called.

3. Add a test

Is this the correct approach?

[r1cebank]

@Fishrock123 @mscdex I will start work on this in favor of deprecation

[benjamingr]

Closed with #15990