fs::canonicalize has some important portability concerns.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index f877c77ad7f..732da79a4d4 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -1708,7 +1708,14 @@ pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
 /// 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
 ///