From 563302ea9a279a466a7c15dbe99350efeb153a82 Mon Sep 17 00:00:00 2001
From: Thalia Archibald <thalia@archibald.dev>
Date: Mon, 20 Oct 2025 21:26:05 -0600
Subject: [PATCH] os_str: Make platform docs more consistent

- Port `Buf::as_slice`/`as_mut_slice` wording from wtf8 to bytes
- Make `Buf::extend_from_slice_unchecked` docs more platform-independent
- wtf8 `Buf` was missing `#[repr(transparent)]`
---
 library/std/src/sys/os_str/bytes.rs | 16 +++++++++-------
 library/std/src/sys/os_str/wtf8.rs  | 11 +++++++----
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/library/std/src/sys/os_str/bytes.rs b/library/std/src/sys/os_str/bytes.rs
index f8ab4543a3a52..9373982c455fa 100644
--- a/library/std/src/sys/os_str/bytes.rs
+++ b/library/std/src/sys/os_str/bytes.rs
@@ -176,17 +176,17 @@ impl Buf {
 
     #[inline]
     pub fn as_slice(&self) -> &Slice {
-        // SAFETY: Slice just wraps [u8],
-        // and &*self.inner is &[u8], therefore
-        // transmuting &[u8] to &Slice is safe.
+        // SAFETY: Slice is just a wrapper for [u8],
+        // and self.inner.as_slice() returns &[u8].
+        // Therefore, transmuting &[u8] to &Slice is safe.
         unsafe { mem::transmute(self.inner.as_slice()) }
     }
 
     #[inline]
     pub fn as_mut_slice(&mut self) -> &mut Slice {
-        // SAFETY: Slice just wraps [u8],
-        // and &mut *self.inner is &mut [u8], therefore
-        // transmuting &mut [u8] to &mut Slice is safe.
+        // SAFETY: Slice is just a wrapper for [u8],
+        // and self.inner.as_mut_slice() returns &mut [u8].
+        // Therefore, transmuting &mut [u8] to &mut Slice is safe.
         unsafe { mem::transmute(self.inner.as_mut_slice()) }
     }
 
@@ -233,7 +233,9 @@ impl Buf {
     ///
     /// # Safety
     ///
-    /// This encoding has no safety requirements.
+    /// The slice must be valid for the platform encoding (as described in
+    /// `OsStr::from_encoded_bytes_unchecked`). This encoding has no safety
+    /// requirements.
     #[inline]
     pub unsafe fn extend_from_slice_unchecked(&mut self, other: &[u8]) {
         self.inner.extend_from_slice(other);
diff --git a/library/std/src/sys/os_str/wtf8.rs b/library/std/src/sys/os_str/wtf8.rs
index 96da891874ef0..208755cd5b9c7 100644
--- a/library/std/src/sys/os_str/wtf8.rs
+++ b/library/std/src/sys/os_str/wtf8.rs
@@ -1,5 +1,6 @@
 //! The underlying OsString/OsStr implementation on Windows is a
 //! wrapper around the "WTF-8" encoding; see the `wtf8` module for more.
+
 use alloc::wtf8::{Wtf8, Wtf8Buf};
 use core::clone::CloneToUninit;
 
@@ -11,6 +12,7 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
 use crate::{fmt, mem};
 
 #[derive(Hash)]
+#[repr(transparent)]
 pub struct Buf {
     pub inner: Wtf8Buf,
 }
@@ -213,11 +215,12 @@ impl Buf {
     /// # Safety
     ///
     /// The slice must be valid for the platform encoding (as described in
-    /// [`Slice::from_encoded_bytes_unchecked`]).
+    /// `OsStr::from_encoded_bytes_unchecked`). For this encoding, that means
+    /// `other` must be valid WTF-8.
     ///
-    /// This bypasses the WTF-8 surrogate joining, so either `self` must not
-    /// end with a leading surrogate half, or `other` must not start with a
-    /// trailing surrogate half.
+    /// Additionally, this method bypasses the WTF-8 surrogate joining, so
+    /// either `self` must not end with a leading surrogate half, or `other`
+    /// must not start with a trailing surrogate half.
     #[inline]
     pub unsafe fn extend_from_slice_unchecked(&mut self, other: &[u8]) {
         unsafe {