Auto merge of #39176 - CartesianDaemon:master, r=frewsxcv

Use fs::symlink_metadata in doc for is_symlink

fs::metadata() follows symlinks so is_symlink() will always return
false. Use symlink_metadata instead in the example in the
documentation.

See issue #39088.

Author: bors

src/libstd/fs.rs

@@ -978,13 +978,24 @@ impl FileType {
 
     /// Test whether this file type represents a symbolic link.
     ///
+    /// The underlying [`Metadata`] struct needs to be retrieved
+    /// with the [`fs::symlink_metadata`] function and not the
+    /// [`fs::metadata`] function. The [`fs::metadata`] function
+    /// follows symbolic links, so [`is_symlink`] would always
+    /// return false for the target file.
+    ///
+    /// [`Metadata`]: struct.Metadata.html
+    /// [`fs::metadata`]: fn.metadata.html
+    /// [`fs::symlink_metadata`]: fn.symlink_metadata.html
+    /// [`is_symlink`]: struct.FileType.html#method.is_symlink
+    ///
     /// # Examples
     ///
     /// ```
     /// # fn foo() -> std::io::Result<()> {
     /// use std::fs;
     ///
-    /// let metadata = try!(fs::metadata("foo.txt"));
+    /// let metadata = try!(fs::symlink_metadata("foo.txt"));
     /// let file_type = metadata.file_type();
     ///
     /// assert_eq!(file_type.is_symlink(), false);