Clarify what values BorrowedHandle, OwnedHandle etc. can hold.

This ports the documentation updates from rust-lang/rust#96932.

Author: sunfishcode

src/types.rs

@@ -70,8 +70,9 @@ pub struct BorrowedFd<'fd> {
 /// so it can be used in FFI in places where a handle is passed as an argument,
 /// it is not captured or consumed, and it is never null.
 ///
-/// Note that it *may* have the value [`INVALID_HANDLE_VALUE`]. See [here] for
-/// the full story.
+/// Note that it *may* have the value `-1`, which in `BorrowedHandle` always
+/// represents the current process handle, and not `INVALID_HANDLE_VALUE`,
+/// despite the two having the same value. See [here] for the full story.
 ///
 /// This type's `.to_owned()` implementation returns another `BorrowedHandle`
 /// rather than an `OwnedHandle`. It just makes a trivial copy of the raw
@@ -187,8 +188,9 @@ impl OwnedFd {
 ///
 /// This closes the handle on drop.
 ///
-/// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is
-/// sometimes a valid handle value. See [here] for the full story.
+/// Note that it *may* have the value `-1`, which in `OwnedHandle` always
+/// represents the current process handle, and not `INVALID_HANDLE_VALUE`,
+/// despite the two having the same value. See [here] for the full story.
 ///
 /// And, it *may* have the value `NULL` (0), which can occur when consoles are
 /// detached from processes, or when `windows_subsystem` is used.
@@ -375,11 +377,10 @@ impl OwnedSocket {
 /// `INVALID_HANDLE_VALUE`. This ensures that such FFI calls cannot start using the handle without
 /// checking for `INVALID_HANDLE_VALUE` first.
 ///
-/// This type concerns any value other than `INVALID_HANDLE_VALUE` to be valid, including `NULL`.
-/// This is because APIs that use `INVALID_HANDLE_VALUE` as their sentry value may return `NULL`
-/// under `windows_subsystem = "windows"` or other situations where I/O devices are detached.
+/// This type may hold any handle value that [`OwnedHandle`] may hold, except that when it holds
+/// `-1`, that value is interpreted to mean `INVALID_HANDLE_VALUE`.
 ///
-/// If this holds a valid handle, it will close the handle on drop.
+/// If holds a handle other than `INVALID_HANDLE_VALUE`, it will close the handle on drop.
 #[cfg(windows)]
 #[repr(transparent)]
 #[derive(Debug)]
@@ -395,11 +396,11 @@ pub struct HandleOrInvalid(RawHandle);
 /// `NULL`. This ensures that such FFI calls cannot start using the handle without
 /// checking for `NULL` first.
 ///
-/// This type concerns any value other than `NULL` to be valid, including `INVALID_HANDLE_VALUE`.
-/// This is because APIs that use `NULL` as their sentry value don't treat `INVALID_HANDLE_VALUE`
-/// as special.
+/// This type may hold any handle value that [`OwnedHandle`] may hold. As with `OwnedHandle`, when
+/// it holds `-1`, that value is interpreted as the current process handle, and not
+/// `INVALID_HANDLE_VALUE`.
 ///
-/// If this holds a valid handle, it will close the handle on drop.
+/// If this holds a non-null handle, it will close the handle on drop.
 #[cfg(windows)]
 #[repr(transparent)]
 #[derive(Debug)]