Add documentation about BorrowedFd::to_owned.

[sunfishcode]

Following up on #88564, this adds documentation explaining why
BorrowedFd::to_owned returns another BorrowedFd rather than an
OwnedFd. And similar for BorrowedHandle and BorrowedSocket.

r? @joshtriplett

[joshtriplett]

What happened with the idea of just omitting the Copy and Clone impls to avoid confusion?

[sunfishcode]

@joshtriplett I added this comment to #88564. It turns out, there are places where having BorrowedFd be Copy is convenient.

[sunfishcode]

Also, if #93869 is accepted, we should expect using BorrowedFd by value to be even more common, because users will be able to use BorrowedFd instead of &BorrowedFd in some common situations.

[sunfishcode]

Also, if #93869 is accepted, we should expect using BorrowedFd by value to be even more common, because users will be able to use BorrowedFd instead of &BorrowedFd in some common situations.

#93869 is now replaced by #93888, but this concern still applies. The common pattern for AsFd APIs is this:

pub fn library_func<Fd: AsFd>(fd: Fd) {
    ...
}

so user code that does something simple like this:

fn user_code(fd: BorrowedFd) {
    library_func(fd);
    library_func(fd);
}

ends up depending on BorrowedFd implementing Copy.

[joshtriplett]

This seems like the best of a bunch of bad options here. We can't make it dup, and even if we could that would also be surprising. It's confusing that to_owned doesn't return OwnedFd, but it can't.

@bors r+ rollup

[bors]

📌 Commit 47aaf79 has been approved by joshtriplett