Rollup merge of rust-lang#50602 - Screwtapello:update-canonicalize-do…

…cs, r=cramertj

Update canonicalize docs

I was recently working with file-paths in Rust, and I felt let down by the `std::fs::canonicalize` docs, so I figured I should submit a PR with some suggestions.

I was looking for a method to turn a relative path into an absolute path. The `canonicalize` docs didn't mention the words "relative" or "absolute", but they did mention resolving symlinks (which is a kind of canonicalisation and does not imply converting to absolute), so I assumed that's all it did. To remedy this, I've added the word "absolute" to the description of both `std::fs::canonicalize` and `std::path::Path::canonicalize`.

After calling `canonicalize` on Windows, I ran into a bunch of other problems I would not have expected from the function's behaviour on Linux. Specifically, if you call `canonicalize` on a path:

  - it's allowed to be much longer than it otherwise would
  - `.join("a/slash/delimited/path")` gives you a broken path that Windows can't use, where the same operation would have worked perfectly without `canonicalize` (if the path were short enough)
  - the resulting path may confuse other Windows programs if you pass it to them on the command-line, or write it to a config file that they read, etc.

...so I tried to summarize those behaviours too.

If I understand correctly, those behaviours are a side-effect of calling `GetFinalPathNameByHandle`, and the documentation says `canonicalize` might not call that function in future, so maybe those side-effects shouldn't be part of the function's documentation. However, I bet there's a lot of applications deliberately calling `canonicalize` just for the path-length-extension alone, so that particular side-effect is de-facto part of the `canonicalize` interface.

src/libstd/fs.rs

@@ -1699,16 +1699,23 @@ pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
     fs_imp::readlink(path.as_ref())
 }
 
-/// Returns the canonical form of a path with all intermediate components
-/// normalized and symbolic links resolved.
+/// Returns the canonical, absolute form of a path with all intermediate
+/// components normalized and symbolic links resolved.
 ///
 /// # Platform-specific behavior
 ///
 /// This function currently corresponds to the `realpath` function on Unix
 /// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows.
 /// Note that, this [may change in the future][changes].
 ///
+/// On Windows, this converts the path to use [extended length path][path]
+/// syntax, which allows your program to use longer path names, but means you
+/// can only join backslash-delimited paths to it, and it may be incompatible
+/// with other applications (if passed to the application on the command-line,
+/// or written to a file another application may read).
+///
 /// [changes]: ../io/index.html#platform-specific-behavior
+/// [path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx#maxpath
 ///
 /// # Errors
 ///

src/libstd/path.rs

@@ -2284,8 +2284,8 @@ impl Path {
         fs::symlink_metadata(self)
     }
 
-    /// Returns the canonical form of the path with all intermediate components
-    /// normalized and symbolic links resolved.
+    /// Returns the canonical, absolute form of the path with all intermediate
+    /// components normalized and symbolic links resolved.
     ///
     /// This is an alias to [`fs::canonicalize`].
     ///