further expand on Arc and Box analogy

1 files changed, 6 insertions, 3 deletions

diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs
index 35f5855d7f9..b3cb21125c7 100644
--- a/library/std/src/io/mod.rs
+++ b/library/std/src/io/mod.rs
@@ -272,9 +272,12 @@
 //! same kernel object. However, when you create a new kernel object, you know that you are holding
 //! the only reference to it. Just be careful not to lend it to anyone, since they can obtain a
 //! clone and then you can no longer know what the reference count is! In that sense, [`OwnedFd`] is
-//! like `Arc` and [`BorrowedFd<'a>`] is like `&'a Arc` (and similar for the Windows types). There
-//! is no equivalent to `Box` for file descriptors in the standard library (that would be a type
-//! that guarantees that the reference count is `1`).
+//! like `Arc` and [`BorrowedFd<'a>`] is like `&'a Arc` (and similar for the Windows types). In
+//! particular, given a `BorrowedFd<'a>`, you are not allowed to close the file descriptor -- just
+//! like how, given a `&'a Arc`, you are not allowed to decrement the reference count and
+//! potentially free the underlying object. There is no equivalent to `Box` for file descriptors in
+//! the standard library (that would be a type that guarantees that the reference count is `1`),
+//! however, it would be possible for a crate to define a type with those semantics.
 //!
 //! [`File`]: crate::fs::File
 //! [`TcpStream`]: crate::net::TcpStream