doc: fill out `fs` and remove html links (#2015)

also add an async version of `fs::canonicalize`

1 files changed, 29 insertions, 2 deletions

diff --git a/tokio/src/fs/hard_link.rs b/tokio/src/fs/hard_link.rs
index e3a32afc..50cc17d2 100644
--- a/tokio/src/fs/hard_link.rs
+++ b/tokio/src/fs/hard_link.rs
@@ -5,12 +5,39 @@ use std::path::Path;
 
 /// Creates a new hard link on the filesystem.
 ///
+/// This is an async version of [`std::fs::hard_link`][std]
+///
+/// [std]: std::fs::hard_link
+///
 /// The `dst` path will be a link pointing to the `src` path. Note that systems
 /// often require these two paths to both be located on the same filesystem.
 ///
-/// This is an async version of [`std::fs::hard_link`][std]
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `link` function on Unix
+/// and the `CreateHardLink` function on Windows.
+/// Note that, this [may change in the future][changes].
+///
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The `src` path is not a file or doesn't exist.
+///
+/// # Examples
+///
+/// ```no_run
+/// use tokio::fs;
 ///
-/// [std]: https://doc.rust-lang.org/std/fs/fn.hard_link.html
+/// #[tokio::main]
+/// async fn main() -> std::io::Result<()> {
+///     fs::hard_link("a.txt", "b.txt").await?; // Hard link a.txt to b.txt
+///     Ok(())
+/// }
+/// ```
 pub async fn hard_link(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();