Skip to content

Commit 516a7fa

Browse files
committed
Relax the wording about the meaning of -1.
1 parent 2f75b4a commit 516a7fa

File tree

1 file changed

+11
-6
lines changed

1 file changed

+11
-6
lines changed

library/std/src/os/windows/io/handle.rs

+11-6
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,9 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
2323
/// it is not captured or consumed.
2424
///
2525
/// Note that it *may* have the value `-1`, which in `BorrowedHandle` always
26-
/// represents the current process handle, and not `INVALID_HANDLE_VALUE`,
27-
/// despite the two having the same value. See [here] for the full story.
26+
/// represents a valid handle value, such as [the current process handle], and
27+
/// not `INVALID_HANDLE_VALUE`, despite the two having the same value. See
28+
/// [here] for the full story.
2829
///
2930
/// And, it *may* have the value `NULL` (0), which can occur when consoles are
3031
/// detached from processes, or when `windows_subsystem` is used.
@@ -34,6 +35,7 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
3435
/// handle, which is then borrowed under the same lifetime.
3536
///
3637
/// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
38+
/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
3739
#[derive(Copy, Clone)]
3840
#[repr(transparent)]
3941
#[unstable(feature = "io_safety", issue = "87074")]
@@ -47,8 +49,9 @@ pub struct BorrowedHandle<'handle> {
4749
/// This closes the handle on drop.
4850
///
4951
/// Note that it *may* have the value `-1`, which in `OwnedHandle` always
50-
/// represents the current process handle, and not `INVALID_HANDLE_VALUE`,
51-
/// despite the two having the same value. See [here] for the full story.
52+
/// represents a valid handle value, such as [the current process handle], and
53+
/// not `INVALID_HANDLE_VALUE`, despite the two having the same value. See
54+
/// [here] for the full story.
5255
///
5356
/// And, it *may* have the value `NULL` (0), which can occur when consoles are
5457
/// detached from processes, or when `windows_subsystem` is used.
@@ -61,6 +64,7 @@ pub struct BorrowedHandle<'handle> {
6164
/// [`RegCloseKey`]: https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regclosekey
6265
///
6366
/// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
67+
/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
6468
#[repr(transparent)]
6569
#[unstable(feature = "io_safety", issue = "87074")]
6670
pub struct OwnedHandle {
@@ -78,10 +82,11 @@ pub struct OwnedHandle {
7882
/// checking for `NULL` first.
7983
///
8084
/// This type may hold any handle value that [`OwnedHandle`] may hold. As with `OwnedHandle`, when
81-
/// it holds `-1`, that value is interpreted as the current process handle, and not
82-
/// `INVALID_HANDLE_VALUE`.
85+
/// it holds `-1`, that value is interpreted as a valid handle value, such as
86+
/// [the current process handle], and not `INVALID_HANDLE_VALUE`.
8387
///
8488
/// If this holds a non-null handle, it will close the handle on drop.
89+
/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks
8590
#[repr(transparent)]
8691
#[unstable(feature = "io_safety", issue = "87074")]
8792
#[derive(Debug)]

0 commit comments

Comments
 (0)