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.

diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index e9390630445a106fbf878479492c212778880e5f..d5a51c02a4778d69d35e08bf21b8a6433ae528b5 100644 (file)
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -42,6 +42,13 @@
 /// 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