os_str: Make platform docs more consistent

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);

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 {