Docs enhancement: misleading try_clone docs

[rbtcollins]

try_clone says it "Creates a new File instance that shares the same underlying file handle as the existing File instance."

However, #45536 notes that it calls DuplicateHandle and fcntl F_DUPFD_CLOEXEC on Windows and other OSes respectively. Those calls create new handles, which point to the same operating system descriptor (file, socket etc).

The distinction is potentially important: file system behaviours that can cause IO latency may be hooked in on syscalls like close() - we've spent considerable time in rustup dealing with virus scanners and NFS for two examples.

I think the documentation should at a minimum say 'new operating system handle cloned from the existing one', or some such. Ideally it would, like other calls do, just say what calls are used: this is clear and unambiguous, and would also solve the problem raised in bug 45536 about documentation about when it may fail by letting folk go and read the underlying syscall documentation.

Meta

This is present still in git. https://doc.rust-lang.org/src/std/fs.rs.html#548

[jyn514]

Perma-link:

rust/library/std/src/fs.rs

Line 504 in 59a1a05

/// Creates a new `File` instance that shares the same underlying file handle

[hkBst]

Still present and the example also seems meh.