Merge #190 #200

190: Clean up the fs module and a few other places r=stjepang a=stjepang

Just a cleanup for various pieces of documentation, mainly around the `lib.rs` docs, the prelude, and the `fs` module. Some small bugs are also fixed along the way.

This PR is the first one in a series of review PRs that I will be submitting before the upcoming 1.0 release.

200: expose IoSlice, IoSliceMut r=stjepang a=yoshuawuyts

Exposes `io::IoSlice` and `io::IoSliceMut`. Given we're returning these from `read_vectored` and `write_vectored` it might make sense to just include them as part of our re-exports. Thanks!

Ref #131.

Co-authored-by: Stjepan Glavina <[email protected]>
Co-authored-by: Yoshua Wuyts <[email protected]>

Author: 3 people

Diff for: Cargo.toml

@@ -3,7 +3,8 @@ name = "async-std"
 version = "0.99.5"
 authors = [
   "Stjepan Glavina <[email protected]>",
-  "The async-std Project Developers",
+  "Yoshua Wuyts <[email protected]>",
+  "Contributors to async-std",
 ]
 edition = "2018"
 license = "Apache-2.0/MIT"

Diff for: README.md

@@ -1,4 +1,4 @@
-# Async version of Rust's standard library
+# Async version of the Rust standard library
 
 [![Build Status](https://travis-ci.com/async-rs/async-std.svg?branch=master)](https://travis-ci.com/async-rs/async-std)
 [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/async-rs/async-std)

Diff for: examples/list-dir.rs

@@ -13,8 +13,9 @@ fn main() -> io::Result<()> {
     task::block_on(async {
         let mut dir = fs::read_dir(&path).await?;
 
-        while let Some(entry) = dir.next().await {
-            println!("{}", entry?.file_name().to_string_lossy());
+        while let Some(res) = dir.next().await {
+            let entry = res?;
+            println!("{}", entry.file_name().to_string_lossy());
         }
 
         Ok(())

Diff for: src/fs/canonicalize.rs

@@ -1,4 +1,3 @@
-use std::fs;
 use std::path::{Path, PathBuf};
 
 use crate::io;
@@ -15,10 +14,11 @@ use crate::task::blocking;
 ///
 /// # Errors
 ///
-/// An error will be returned in the following situations (not an exhaustive list):
+/// An error will be returned in the following situations:
 ///
-/// * `path` does not exist.
-/// * A non-final component in path is not a directory.
+/// * `path` does not point to an existing file or directory.
+/// * A non-final component in `path` is not a directory.
+/// * Some other I/O error occurred.
 ///
 /// # Examples
 ///
@@ -33,5 +33,5 @@ use crate::task::blocking;
 /// ```
 pub async fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
     let path = path.as_ref().to_owned();
-    blocking::spawn(async move { fs::canonicalize(path) }).await
+    blocking::spawn(async move { std::fs::canonicalize(path) }).await
 }

Diff for: src/fs/copy.rs

@@ -1,28 +1,32 @@
-use std::fs;
 use std::path::Path;
 
 use crate::io;
 use crate::task::blocking;
 
-/// Copies the contents and permissions of one file to another.
+/// Copies the contents and permissions of a file to a new location.
 ///
-/// On success, the total number of bytes copied is returned and equals the length of the `from`
-/// file.
+/// On success, the total number of bytes copied is returned and equals the length of the `to` file
+/// after this operation.
 ///
 /// The old contents of `to` will be overwritten. If `from` and `to` both point to the same file,
-/// then the file will likely get truncated by this operation.
+/// then the file will likely get truncated as a result of this operation.
+///
+/// If you're working with open [`File`]s and want to copy contents through those types, use the
+/// [`io::copy`] function.
 ///
 /// This function is an async version of [`std::fs::copy`].
 ///
+/// [`File`]: struct.File.html
+/// [`io::copy`]: ../io/fn.copy.html
 /// [`std::fs::copy`]: https://doc.rust-lang.org/std/fs/fn.copy.html
 ///
 /// # Errors
 ///
-/// An error will be returned in the following situations (not an exhaustive list):
+/// An error will be returned in the following situations:
 ///
-/// * The `from` path is not a file.
-/// * The `from` file does not exist.
-/// * The current process lacks permissions to access `from` or write `to`.
+/// * `from` does not point to an existing file.
+/// * The current process lacks permissions to read `from` or write `to`.
+/// * Some other I/O error occurred.
 ///
 /// # Examples
 ///
@@ -31,12 +35,12 @@ use crate::task::blocking;
 /// #
 /// use async_std::fs;
 ///
-/// let bytes_copied = fs::copy("a.txt", "b.txt").await?;
+/// let num_bytes = fs::copy("a.txt", "b.txt").await?;
 /// #
 /// # Ok(()) }) }
 /// ```
 pub async fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
     let from = from.as_ref().to_owned();
     let to = to.as_ref().to_owned();
-    blocking::spawn(async move { fs::copy(&from, &to) }).await
+    blocking::spawn(async move { std::fs::copy(&from, &to) }).await
 }

Diff for: src/fs/create_dir.rs

@@ -1,22 +1,26 @@
-use std::fs;
 use std::path::Path;
 
 use crate::io;
 use crate::task::blocking;
 
-/// Creates a new, empty directory.
+/// Creates a new directory.
+///
+/// Note that this function will only create the final directory in `path`. If you want to create
+/// all of its missing parent directories too, use the [`create_dir_all`] function instead.
 ///
 /// This function is an async version of [`std::fs::create_dir`].
 ///
+/// [`create_dir_all`]: fn.create_dir_all.html
 /// [`std::fs::create_dir`]: https://doc.rust-lang.org/std/fs/fn.create_dir.html
 ///
 /// # Errors
 ///
-/// An error will be returned in the following situations (not an exhaustive list):
+/// An error will be returned in the following situations:
 ///
-/// * `path` already exists.
-/// * A parent of the given path does not exist.
-/// * The current process lacks permissions to create directory at `path`.
+/// * `path` already points to an existing file or directory.
+/// * A parent directory in `path` does not exist.
+/// * The current process lacks permissions to create the directory.
+/// * Some other I/O error occurred.
 ///
 /// # Examples
 ///
@@ -25,11 +29,11 @@ use crate::task::blocking;
 /// #
 /// use async_std::fs;
 ///
-/// fs::create_dir("./some/dir").await?;
+/// fs::create_dir("./some/directory").await?;
 /// #
 /// # Ok(()) }) }
 /// ```
 pub async fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
     let path = path.as_ref().to_owned();
-    blocking::spawn(async move { fs::create_dir(path) }).await
+    blocking::spawn(async move { std::fs::create_dir(path) }).await
 }

Diff for: src/fs/create_dir_all.rs

@@ -1,21 +1,21 @@
-use std::fs;
 use std::path::Path;
 
 use crate::io;
 use crate::task::blocking;
 
-/// Creates a new, empty directory and all of its parents if they are missing.
+/// Creates a new directory and all of its parents if they are missing.
 ///
 /// This function is an async version of [`std::fs::create_dir_all`].
 ///
 /// [`std::fs::create_dir_all`]: https://doc.rust-lang.org/std/fs/fn.create_dir_all.html
 ///
 /// # Errors
 ///
-/// An error will be returned in the following situations (not an exhaustive list):
+/// An error will be returned in the following situations:
 ///
-/// * The parent directories do not exists and couldn't be created.
-/// * The current process lacks permissions to create directory at `path`.
+/// * `path` already points to an existing file or directory.
+/// * The current process lacks permissions to create the directory or its missing parents.
+/// * Some other I/O error occurred.
 ///
 /// # Examples
 ///
@@ -24,11 +24,11 @@ use crate::task::blocking;
 /// #
 /// use async_std::fs;
 ///
-/// fs::create_dir_all("./some/dir").await?;
+/// fs::create_dir_all("./some/directory").await?;
 /// #
 /// # Ok(()) }) }
 /// ```
 pub async fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
     let path = path.as_ref().to_owned();
-    blocking::spawn(async move { fs::create_dir_all(path) }).await
+    blocking::spawn(async move { std::fs::create_dir_all(path) }).await
 }

Diff for: src/fs/dir_builder.rs

@@ -1,4 +1,3 @@
-use std::fs;
 use std::path::Path;
 
 use cfg_if::cfg_if;
@@ -7,21 +6,28 @@ use crate::future::Future;
 use crate::io;
 use crate::task::blocking;
 
-/// A builder for creating directories in various manners.
+/// A builder for creating directories with configurable options.
+///
+/// For Unix-specific options, import the [`os::unix::fs::DirBuilderExt`] trait.
 ///
 /// This type is an async version of [`std::fs::DirBuilder`].
 ///
+/// [`os::unix::fs::DirBuilderExt`]: ../os/unix/fs/trait.DirBuilderExt.html
 /// [`std::fs::DirBuilder`]: https://doc.rust-lang.org/std/fs/struct.DirBuilder.html
 #[derive(Debug)]
 pub struct DirBuilder {
+    /// Set to `true` if non-existent parent directories should be created.
     recursive: bool,
 
+    /// Unix mode for newly created directories.
     #[cfg(unix)]
     mode: Option<u32>,
 }
 
 impl DirBuilder {
-    /// Creates a new builder with [`recursive`] set to `false`.
+    /// Creates a blank set of options.
+    ///
+    /// The [`recursive`] option is initially set to `false`.
     ///
     /// [`recursive`]: #method.recursive
     ///
@@ -33,25 +39,24 @@ impl DirBuilder {
     /// let builder = DirBuilder::new();
     /// ```
     pub fn new() -> DirBuilder {
+        #[cfg(not(unix))]
+        let builder = DirBuilder { recursive: false };
+
         #[cfg(unix)]
         let builder = DirBuilder {
             recursive: false,
             mode: None,
         };
 
-        #[cfg(windows)]
-        let builder = DirBuilder { recursive: false };
-
         builder
     }
 
     /// Sets the option for recursive mode.
     ///
-    /// This option, when `true`, means that all parent directories should be created recursively
-    /// if they don't exist. Parents are created with the same security settings and permissions as
-    /// the final directory.
+    /// When set to `true`, this option means all parent directories should be created recursively
+    /// if they don't exist. Parents are created with the same permissions as the final directory.
     ///
-    /// This option defaults to `false`.
+    /// This option is initially set to `false`.
     ///
     /// # Examples
     ///
@@ -70,6 +75,14 @@ impl DirBuilder {
     ///
     /// It is considered an error if the directory already exists unless recursive mode is enabled.
     ///
+    /// # Errors
+    ///
+    /// An error will be returned in the following situations:
+    ///
+    /// * `path` already points to an existing file or directory.
+    /// * The current process lacks permissions to create the directory or its missing parents.
+    /// * Some other I/O error occurred.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -79,13 +92,13 @@ impl DirBuilder {
     ///
     /// DirBuilder::new()
     ///     .recursive(true)
-    ///     .create("/tmp/foo/bar/baz")
+    ///     .create("./some/directory")
     ///     .await?;
     /// #
     /// # Ok(()) }) }
     /// ```
     pub fn create<P: AsRef<Path>>(&self, path: P) -> impl Future<Output = io::Result<()>> {
-        let mut builder = fs::DirBuilder::new();
+        let mut builder = std::fs::DirBuilder::new();
         builder.recursive(self.recursive);
 
         #[cfg(unix)]