Update docs to conform to Tokio standards

src/fs/directory.rs

@@ -2,6 +2,21 @@ use crate::runtime::driver::op::Op;
 use std::io;
 use std::path::Path;
 
+/// Creates a directory on the local filesystem.
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * User lacks permissions to create a directory at `path`
+///      * [`io::ErrorKind`] would be set to `PermissionDenied`
+/// * A parent of the given path doesn't exist.
+///      * [`io::ErrorKind`] would be set to `NotFound` or `NotADirectory`
+/// * `path` already exists.
+///      * [`io::ErrorKind`] would be set to `AlreadyExists`
+///
+/// [`ErrorKind`]: std::io::ErrorKind
 /// # Examples
 ///
 /// ```no_run
@@ -19,7 +34,27 @@ pub async fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
     Op::make_dir(path.as_ref())?.await
 }
 
-/// Removes an empty directory.
+/// Removes a directory on the local filesystem.
+///
+/// This will only remove empty directories with no children. If you want to destroy the entire
+/// contents of a directory, you may try [`remove_dir_all`] which uses the standard Tokio executor.
+/// There currently is no implementation of `remove_dir_all` in tokio-uring.
+///
+/// [`remove_dir_all`]: https://docs.rs/tokio/latest/tokio/fs/fn.remove_dir_all.html
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` doesn't exist.
+///      * [`io::ErrorKind`] would be set to `NotFound`
+/// * `path` isn't a directory.
+///      * [`io::ErrorKind`] would be set to `NotADirectory`
+/// * The user lacks permissions to modify/remove the directory at the provided `path`.
+///      * [`io::ErrorKind`] would be set to `PermissionDenied`
+/// * The directory isn't empty.
+///      * [`io::ErrorKind`] would be set to `DirectoryNotEmpty`
 ///
 /// # Examples
 ///

src/fs/file.rs

@@ -877,6 +877,14 @@ impl fmt::Debug for File {
 
 /// Removes a File
 ///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` doesn't exist.
+///      * [`io::ErrorKind`] would be set to `NotFound`
+/// * The user lacks permissions to modify/remove the file at the provided `path`.
+///      * [`io::ErrorKind`] would be set to `PermissionDenied`
+///
 /// # Examples
 ///
 /// ```no_run
@@ -897,7 +905,14 @@ pub async fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
 /// Renames a file or directory to a new name, replacing the original file if
 /// `to` already exists.
 ///
-/// This will not work if the new name is on a different mount point.
+/// #Errors
+///
+/// * `path` doesn't exist.
+///      * [`io::ErrorKind`] would be set to `NotFound`
+/// * The user lacks permissions to modify/remove the file at the provided `path`.
+///      * [`io::ErrorKind`] would be set to `PermissionDenied`
+/// * The new name/path is on a different mount point.
+///      * [`io::ErrorKind`] would be set to `CrossesDevices`
 ///
 /// # Example
 ///

src/lib.rs

@@ -84,7 +84,7 @@ pub use runtime::Runtime;
 use crate::runtime::driver::op::Op;
 use std::future::Future;
 
-/// Start an `io_uring` enabled Tokio runtime.
+/// Starts an `io_uring` enabled Tokio runtime.
 ///
 /// All `tokio-uring` resource types must be used from within the context of a
 /// runtime. The `start` method initializes the runtime and runs it for the
@@ -146,7 +146,7 @@ pub fn start<F: Future>(future: F) -> F::Output {
     rt.block_on(future)
 }
 
-/// Create and return an io_uring::Builder that can then be modified
+/// Creates and returns an io_uring::Builder that can then be modified
 /// through its implementation methods.
 ///
 /// This function is provided to avoid requiring the user of this crate from
@@ -156,18 +156,20 @@ pub fn uring_builder() -> io_uring::Builder {
     io_uring::IoUring::builder()
 }
 
-/// Builder API to allow starting the runtime and creating the io_uring driver with non-default
-/// parameters.
+/// Builder API that can create and start the `io_uring` runtime with non-default parameters,
+/// while abstracting away the underlying io_uring crate.
 // #[derive(Clone, Default)]
 pub struct Builder {
     entries: u32,
     urb: io_uring::Builder,
 }
 
-/// Return a Builder to allow setting parameters before calling the start method.
-/// Returns a Builder with our default values, all of which can be replaced with the methods below.
+/// Constructs a [`Builder`] with default settings.
 ///
-/// Refer to Builder::start for an example.
+/// Use this to alter submission and completion queue parameters, and to create the io_uring
+/// Runtime.
+///
+/// Refer to [`Builder::start`] for an example.
 pub fn builder() -> Builder {
     Builder {
         entries: 256,
@@ -176,30 +178,27 @@ pub fn builder() -> Builder {
 }
 
 impl Builder {
-    /// Set number of submission queue entries in uring.
-    ///
-    /// The kernel will ensure it uses a power of two and will round this up if necessary.
-    /// The kernel requires the number of completion queue entries to be larger than
-    /// the submission queue entries so generally will double the sq entries count.
+    /// Sets the number of Submission Queue entries in uring.
     ///
-    /// The caller can specify even a larger cq entries count by using the uring_builder
-    /// as shown in the start example below.
-    pub fn entries(&mut self, e: u32) -> &mut Self {
-        self.entries = e;
+    /// The default value is 256.
+    /// The kernel requires the number of submission queue entries to be a power of two,
+    /// and that it be less than the number of completion queue entries.
+    /// This function will adjust the `cq_entries` value to be at least 2 times `sq_entries`
+    pub fn entries(&mut self, sq_entries: u32) -> &mut Self {
+        self.entries = sq_entries;
         self
     }
 
-    /// Replace the default io_uring Builder. This allows the caller to craft the io_uring Builder
-    /// using the io_uring crate's Builder API.
+    /// Replaces the default [`io_uring::Builder`], which controls the settings for the
+    /// inner `io_uring` API.
     ///
-    /// Refer to the Builder start method for an example.
-    /// Refer to the io_uring::builder documentation for all the supported methods.
+    /// Refer to the [`io_uring::Builder`] documentation for all the supported methods.
     pub fn uring_builder(&mut self, b: &io_uring::Builder) -> &mut Self {
         self.urb = b.clone();
         self
     }
 
-    /// Start an `io_uring` enabled Tokio runtime.
+    /// Starts an `io_uring` enabled Tokio runtime.
     ///
     /// # Examples
     ///

src/net/tcp/stream.rs

@@ -70,12 +70,15 @@ impl TcpStream {
         Self { inner }
     }
 
-    /// Read some data from the stream into the buffer, returning the original buffer and
-    /// quantity of data read.
+    /// Read some data from the stream into the buffer.
+    ///
+    /// Returns the original buffer and quantity of data read.
     pub async fn read<T: BoundedBufMut>(&self, buf: T) -> crate::BufResult<usize, T> {
         self.inner.read(buf).await
     }
 
+    /// Read some data from the stream into a registered buffer.
+    ///
     /// Like [`read`], but using a pre-mapped buffer
     /// registered with [`FixedBufRegistry`].
     ///
@@ -94,8 +97,9 @@ impl TcpStream {
         self.inner.read_fixed(buf).await
     }
 
-    /// Write some data to the stream from the buffer, returning the original buffer and
-    /// quantity of data written.
+    /// Write some data to the stream from the buffer.
+    ///
+    /// Returns the original buffer and quantity of data written.
     pub async fn write<T: BoundedBuf>(&self, buf: T) -> crate::BufResult<usize, T> {
         self.inner.write(buf).await
     }
@@ -154,6 +158,8 @@ impl TcpStream {
         self.inner.write_all(buf).await
     }
 
+    /// Writes data into the socket from a registered buffer.
+    ///
     /// Like [`write`], but using a pre-mapped buffer
     /// registered with [`FixedBufRegistry`].
     ///
@@ -184,16 +190,15 @@ impl TcpStream {
     ///
     /// This function will return the first error that [`write_fixed`] returns.
     ///
-    /// [`write_fixed`]: Self::write
+    /// [`write_fixed`]: Self::write_fixed
     pub async fn write_fixed_all<T>(&self, buf: T) -> crate::BufResult<(), T>
     where
         T: BoundedBuf<Buf = FixedBuf>,
     {
         self.inner.write_fixed_all(buf).await
     }
 
-    /// Write data from buffers into this socket returning how many bytes were
-    /// written.
+    /// Writes data from multiple buffers into this socket using the scatter/gather IO style.
     ///
     /// This function will attempt to write the entire contents of `bufs`, but
     /// the entire write may not succeed, or the write may also generate an

src/net/udp.rs

@@ -92,12 +92,15 @@ pub struct UdpSocket {
 
 impl UdpSocket {
     /// Creates a new UDP socket and attempt to bind it to the addr provided.
+    ///
+    /// Returns a new instance of [`UdpSocket`] on success,
+    /// or an [`io::Error`](std::io::Error) on failure.
     pub async fn bind(socket_addr: SocketAddr) -> io::Result<UdpSocket> {
         let socket = Socket::bind(socket_addr, libc::SOCK_DGRAM)?;
         Ok(UdpSocket { inner: socket })
     }
 
-    /// Returns the local address that this UDP socket is bound to.
+    /// Returns the local address to which this UDP socket is bound.
     ///
     /// This can be useful, for example, when binding to port 0 to
     /// figure out which port was actually bound.
@@ -183,19 +186,21 @@ impl UdpSocket {
         Self { inner }
     }
 
-    /// Connects this UDP socket to a remote address, allowing the `write` and
-    /// `read` syscalls to be used to send data and also applies filters to only
-    /// receive data from the specified address.
+    /// "Connects" this UDP socket to a remote address.
+    ///
+    /// This enables `write` and `read` syscalls to be used on this instance.
+    /// It also constrains the `read` to receive data only from the specified remote peer.
     ///
-    /// Note that usually, a successful `connect` call does not specify
-    /// that there is a remote server listening on the port, rather, such an
-    /// error would only be detected after the first send.
+    /// Note: UDP is connectionless, so a successful `connect` call does not execute
+    /// a handshake or validation of the remote peer of any kind.
+    /// Any errors would not be detected until the first send.
     pub async fn connect(&self, socket_addr: SocketAddr) -> io::Result<()> {
         self.inner.connect(SockAddr::from(socket_addr)).await
     }
 
-    /// Sends data on the socket to the given address. On success, returns the
-    /// number of bytes written.
+    /// Sends data on the socket to the given address.
+    ///
+    /// On success, returns the number of bytes written.
     pub async fn send_to<T: BoundedBuf>(
         &self,
         buf: T,
@@ -205,6 +210,7 @@ impl UdpSocket {
     }
 
     /// Sends data on the socket. Will attempt to do so without intermediate copies.
+    ///
     /// On success, returns the number of bytes written.
     ///
     /// See the linux [kernel docs](https://www.kernel.org/doc/html/latest/networking/msg_zerocopy.html)
@@ -221,6 +227,22 @@ impl UdpSocket {
     }
 
     /// Sends a message on the socket using a msghdr.
+    ///
+    /// Returns a tuple of:
+    ///
+    /// * Result containing bytes written on success
+    /// * The original `io_slices` `Vec<T>`
+    /// * The original `msg_contol` `Option<U>`
+    ///
+    /// See the linux [kernel docs](https://www.kernel.org/doc/html/latest/networking/msg_zerocopy.html)
+    /// for a discussion on when this might be appropriate. In particular:
+    ///
+    /// > Copy avoidance is not a free lunch. As implemented, with page pinning,
+    /// > it replaces per byte copy cost with page accounting and completion
+    /// > notification overhead. As a result, zero copy is generally only effective
+    /// > at writes over around 10 KB.
+    ///
+    /// Note: Using fixed buffers [#54](https://github.com/tokio-rs/tokio-uring/pull/54), avoids the page-pinning overhead
     pub async fn sendmsg_zc<T: IoBuf, U: IoBuf>(
         &self,
         io_slices: Vec<T>,
@@ -232,21 +254,25 @@ impl UdpSocket {
             .await
     }
 
-    /// Receives a single datagram message on the socket. On success, returns
-    /// the number of bytes read and the origin.
+    /// Receives a single datagram message on the socket.
+    ///
+    /// On success, returns the number of bytes read and the origin.
     pub async fn recv_from<T: BoundedBufMut>(
         &self,
         buf: T,
     ) -> crate::BufResult<(usize, SocketAddr), T> {
         self.inner.recv_from(buf).await
     }
 
-    /// Read a packet of data from the socket into the buffer, returning the original buffer and
-    /// quantity of data read.
+    /// Reads a packet of data from the socket into the buffer.
+    ///
+    /// Returns the original buffer and quantity of data read.
     pub async fn read<T: BoundedBufMut>(&self, buf: T) -> crate::BufResult<usize, T> {
         self.inner.read(buf).await
     }
 
+    /// Receives a single datagram message into a registered buffer.
+    ///
     /// Like [`read`], but using a pre-mapped buffer
     /// registered with [`FixedBufRegistry`].
     ///
@@ -265,12 +291,15 @@ impl UdpSocket {
         self.inner.read_fixed(buf).await
     }
 
-    /// Write some data to the socket from the buffer, returning the original buffer and
-    /// quantity of data written.
+    /// Writes data into the socket from the specified buffer.
+    ///
+    /// Returns the original buffer and quantity of data written.
     pub async fn write<T: BoundedBuf>(&self, buf: T) -> crate::BufResult<usize, T> {
         self.inner.write(buf).await
     }
 
+    /// Writes data into the socket from a registered buffer.
+    ///
     /// Like [`write`], but using a pre-mapped buffer
     /// registered with [`FixedBufRegistry`].
     ///
@@ -291,7 +320,7 @@ impl UdpSocket {
 
     /// Shuts down the read, write, or both halves of this connection.
     ///
-    /// This function will cause all pending and future I/O on the specified portions to return
+    /// This function causes all pending and future I/O on the specified portions to return
     /// immediately with an appropriate value.
     pub fn shutdown(&self, how: std::net::Shutdown) -> io::Result<()> {
         self.inner.shutdown(how)