std: Add capacity guarantees notes for OsString

Signed-off-by: Xuanwo <[email protected]>

Author: Xuanwo

library/std/src/ffi/os_str.rs

@@ -45,6 +45,11 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
 /// values, encoded in a less-strict variant of UTF-8. This is useful to
 /// understand when handling capacity and length values.
 ///
+/// # Capacity of OsString
+///
+/// Capacity means UTF-8 byte size for OS strings which created from
+/// valid unicode, and not otherwise specified for other contents.
+///
 /// # Creating an `OsString`
 ///
 /// **From a Rust string**: `OsString` implements
@@ -188,6 +193,11 @@ impl OsString {
     ///
     /// See main `OsString` documentation information about encoding.
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Examples
     ///
     /// ```
@@ -231,6 +241,11 @@ impl OsString {
     ///
     /// See `OsString` introduction for information about encoding.
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Examples
     ///
     /// ```
@@ -272,6 +287,11 @@ impl OsString {
     /// greater than or equal to `self.len() + additional`. Does nothing if
     /// capacity is already sufficient.
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Errors
     ///
     /// If the capacity overflows, or the allocator reports a failure, then an error
@@ -313,6 +333,11 @@ impl OsString {
     ///
     /// [`reserve`]: OsString::reserve
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Examples
     ///
     /// ```
@@ -340,6 +365,11 @@ impl OsString {
     ///
     /// [`try_reserve`]: OsString::try_reserve
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Errors
     ///
     /// If the capacity overflows, or the allocator reports a failure, then an error
@@ -399,6 +429,11 @@ impl OsString {
     ///
     /// If the current capacity is less than the lower limit, this is a no-op.
     ///
+    /// # Notes
+    ///
+    /// Capacity means UTF-8 byte size for OS strings which created from
+    /// valid unicode, and not otherwise specified for other contents.
+    ///
     /// # Examples
     ///
     /// ```