std: Add capacity guarantees notes for OsString

Signed-off-by: Xuanwo <github@xuanwo.io>

library/std/src/ffi/os_str.rs

@@ -45,6 +45,11 @@
 /// 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 @@ pub fn push<T: AsRef<OsStr>>(&mut self, s: T) {
     ///
     /// 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 @@ pub fn clear(&mut self) {
     ///
     /// 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 @@ pub fn reserve(&mut self, additional: usize) {
     /// 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 @@ pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>
     ///
     /// [`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 @@ pub fn reserve_exact(&mut self, additional: usize) {
     ///
     /// [`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 @@ pub fn shrink_to_fit(&mut self) {
     ///
     /// 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
     ///
     /// ```