OsString: mention storage form in discussion

Helps users to understand capacity related values, which may surpise on
Windows.

Also is a step towards clarifying understanding of `OsStr`'s len() return
value.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index e9390630445..d5a51c02a47 100644
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -42,6 +42,13 @@ use sys_common::{AsInner, IntoInner, FromInner};
 /// in each pair are owned strings; the latter are borrowed
 /// references.
 ///
+/// Note, `OsString` and `OsStr` internally do not necessarily hold strings in
+/// the form native to the platform; While on Unix, strings are stored as a
+/// sequence of 8-bit values, on Windows, where strings are 16-bit value based
+/// as just discussed, strings are also actually stored as a sequence of 8-bit
+/// values, encoded in a less-strict variant of UTF-8. This is useful to
+/// understand when handling capacity and length values.
+///
 /// # Creating an `OsString`
 ///
 /// **From a Rust string**: `OsString` implements