Stabilize std::path

This commit stabilizes essentially all of the new `std::path` API. The
API itself is changed in a couple of ways (which brings it in closer
alignment with the RFC):

* `.` components are now normalized away, unless they appear at the
  start of a path. This in turn effects the semantics of e.g. asking for
  the file name of `foo/` or `foo/.`, both of which yield `Some("foo")`
  now. This semantics is what the original RFC specified, and is also
  desirable given early experience rolling out the new API.

* The `parent` function now succeeds if, and only if, the path has at
  least one non-root/prefix component. This change affects `pop` as
  well.

* The `Prefix` component now involves a separate `PrefixComponent`
  struct, to better allow for keeping both parsed and unparsed prefix data.

In addition, the `old_path` module is now deprecated.

Closes #23264

[breaking-change]

1 files changed, 6 insertions, 2 deletions

diff --git a/src/libstd/sys/windows/ext.rs b/src/libstd/sys/windows/ext.rs
index b30aec08439..1d63da813c9 100644
--- a/src/libstd/sys/windows/ext.rs
+++ b/src/libstd/sys/windows/ext.rs
@@ -122,7 +122,7 @@ impl AsRawSocket for net::UdpSocket {
     fn as_raw_socket(&self) -> Socket { *self.as_inner().socket().as_inner() }
 }
 
-// Windows-specific extensions to `OsString`.
+/// Windows-specific extensions to `OsString`.
 pub trait OsStringExt {
     /// Create an `OsString` from a potentially ill-formed UTF-16 slice of 16-bit code units.
     ///
@@ -137,8 +137,12 @@ impl OsStringExt for OsString {
     }
 }
 
-// Windows-specific extensions to `OsStr`.
+/// Windows-specific extensions to `OsStr`.
 pub trait OsStrExt {
+    /// Re-encode an `OsStr` as a wide character sequence,
+    /// i.e. potentially ill-formed UTF-16.
+    ///
+    /// This is lossless. Note that the encoding does not include a final null.
     fn encode_wide(&self) -> EncodeWide;
 }