From 516a7fa6934c561e9fc1b357a57eb5f0adb89739 Mon Sep 17 00:00:00 2001
From: Dan Gohman <dev@sunfishcode.online>
Date: Wed, 11 May 2022 20:50:07 -0700
Subject: [PATCH] Relax the wording about the meaning of -1.

---
 library/std/src/os/windows/io/handle.rs | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/library/std/src/os/windows/io/handle.rs b/library/std/src/os/windows/io/handle.rs
index 81ae1539acb..e473fac3518 100644
--- a/library/std/src/os/windows/io/handle.rs
+++ b/library/std/src/os/windows/io/handle.rs
@@ -23,8 +23,9 @@
 /// it is not captured or consumed.
 ///
 /// 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.
+/// represents a valid handle value, such as [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.
@@ -34,6 +35,7 @@
 /// handle, which is then borrowed under the same lifetime.
 ///
 /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
+/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
 #[derive(Copy, Clone)]
 #[repr(transparent)]
 #[unstable(feature = "io_safety", issue = "87074")]
@@ -47,8 +49,9 @@ pub struct BorrowedHandle<'handle> {
 /// This closes the handle on drop.
 ///
 /// 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.
+/// represents a valid handle value, such as [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.
@@ -61,6 +64,7 @@ pub struct BorrowedHandle<'handle> {
 /// [`RegCloseKey`]: https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regclosekey
 ///
 /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
+/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
 #[repr(transparent)]
 #[unstable(feature = "io_safety", issue = "87074")]
 pub struct OwnedHandle {
@@ -78,10 +82,11 @@ pub struct OwnedHandle {
 /// checking for `NULL` first.
 ///
 /// 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`.
+/// it holds `-1`, that value is interpreted as a valid handle value, such as
+/// [the current process handle], and not `INVALID_HANDLE_VALUE`.
 ///
 /// If this holds a non-null handle, it will close the handle on drop.
+/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
 #[repr(transparent)]
 #[unstable(feature = "io_safety", issue = "87074")]
 #[derive(Debug)]