Rollup merge of #42955 - matklad:doc-path, r=steveklabnik

Document that `/` works as separator on Windows

Hi Whenever I see code like `Path::new("./src/bin/main.rs")` or `path.ends_with("foo/bar")`, I wonder if it will work on Windows as I expect. Unfortunately, reading the current docs does not help to answer this question, because all examples are Unix-specific.

However, I believe that using `/` is fine, because both Windows itself [and Rust stdlib](https://github.com/rust-lang/rust/blob/47faf1d51952ecd9d4c8a7325332fba34fbe00bd/src/libstd/sys/windows/path.rs#L26) do treat it as a file separator, and because it is [actually used](https://github.com/rust-lang/cargo/blob/abf01e1eddb3145c83f71b469ea7bee37141e5e1/tests/git.rs#L579) in Cargo. So looks like we can just document it?

r? @steveklabnik

cc @retep998 I don't actually program for windows that much, so I might be totally wrong, and perhaps we should advise to always use (allocating) `.join` method to construct paths of more than one component?

Author: Ariel Ben-Yehuda

src/libstd/path.rs

@@ -276,7 +276,7 @@ impl<'a> Prefix<'a> {
 /// ```
 /// use std::path;
 ///
-/// assert!(path::is_separator('/'));
+/// assert!(path::is_separator('/')); // '/' works for both Unix and Windows
 /// assert!(!path::is_separator('❤'));
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -1499,9 +1499,9 @@ impl AsRef<OsStr> for PathBuf {
 /// A slice of a path (akin to [`str`]).
 ///
 /// This type supports a number of operations for inspecting a path, including
-/// breaking the path into its components (separated by `/` or `\`, depending on
-/// the platform), extracting the file name, determining whether the path is
-/// absolute, and so on.
+/// breaking the path into its components (separated by `/` on Unix and by either
+/// `/` or `\` on Windows), extracting the file name, determining whether the path
+/// is absolute, and so on.
 ///
 /// This is an *unsized* type, meaning that it must always be used behind a
 /// pointer like `&` or [`Box`]. For an owned version of this type,
@@ -1520,10 +1520,11 @@ impl AsRef<OsStr> for PathBuf {
 /// use std::path::Path;
 /// use std::ffi::OsStr;
 ///
-/// let path = Path::new("/tmp/foo/bar.txt");
+/// // Note: this example does work on Windows
+/// let path = Path::new("./foo/bar.txt");
 ///
 /// let parent = path.parent();
-/// assert_eq!(parent, Some(Path::new("/tmp/foo")));
+/// assert_eq!(parent, Some(Path::new("./foo")));
 ///
 /// let file_stem = path.file_stem();
 /// assert_eq!(file_stem, Some(OsStr::new("bar")));