Fix some cargo doc warnings.

cap-async-std/src/fs/dir.rs

@@ -136,7 +136,7 @@ impl Dir {
     /// This corresponds to [`async_std::fs::create_dir`], but only accesses
     /// paths relative to `self`.
     ///
-    /// TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51
+    /// TODO: async: fix this when we fix <https://github.com/bytecodealliance/cap-std/issues/51>
     #[inline]
     pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
         self._create_dir_one(path.as_ref(), &DirOptions::new())
@@ -148,7 +148,7 @@ impl Dir {
     /// This corresponds to [`async_std::fs::create_dir_all`], but only
     /// accesses paths relative to `self`.
     ///
-    /// TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51
+    /// TODO: async: fix this when we fix <https://github.com/bytecodealliance/cap-std/issues/51>
     #[inline]
     pub fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
         self._create_dir_all(path.as_ref(), &DirOptions::new())
@@ -159,7 +159,7 @@ impl Dir {
     ///
     /// This corresponds to [`async_std::fs::DirBuilder::create`].
     ///
-    /// TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51
+    /// TODO: async: fix this when we fix <https://github.com/bytecodealliance/cap-std/issues/51>
     #[inline]
     pub fn create_dir_with<P: AsRef<Path>>(
         &self,
@@ -415,9 +415,9 @@ impl Dir {
 
     /// Remove the directory referenced by `self` and consume `self`.
     ///
-    /// Note that even though this implementation works in terms of handles
-    /// as much as possible, removal is not guaranteed to be atomic with
-    /// respect to a concurrent rename of the directory.
+    /// Even though this implementation works in terms of handles as much as
+    /// possible, removal is not guaranteed to be atomic with respect to a
+    /// concurrent rename of the directory.
     #[inline]
     pub async fn remove_open_dir(self) -> io::Result<()> {
         let file = std::fs::File::from_into_filelike(self.std_file);
@@ -427,9 +427,9 @@ impl Dir {
     /// Removes the directory referenced by `self`, after removing all its
     /// contents, and consume `self`. Use carefully!
     ///
-    /// Note that even though this implementation works in terms of handles
-    /// as much as possible, removal is not guaranteed to be atomic with
-    /// respect to a concurrent rename of the directory.
+    /// Even though this implementation works in terms of handles as much as
+    /// possible, removal is not guaranteed to be atomic with respect to a
+    /// concurrent rename of the directory.
     #[inline]
     pub async fn remove_open_dir_all(self) -> io::Result<()> {
         let file = std::fs::File::from_into_filelike(self.std_file);
@@ -756,8 +756,8 @@ impl Dir {
 
     /// Returns `true` if the path points at an existing entity.
     ///
-    /// This is an asynchronous version of [`std::fs::try_exists`], and also only
-    /// accesses paths relative to `self`.
+    /// This is an asynchronous version of [`std::fs::try_exists`], and also
+    /// only accesses paths relative to `self`.
     ///
     /// NOTE: This API is not yet part of `async_std`.
     #[inline]

cap-async-std/src/fs/dir_entry.rs

@@ -19,9 +19,9 @@ use std::fmt;
 /// opening or removing the entry directly, which can be more efficient and
 /// convenient.
 ///
-/// Note that there is no `from_std` method, as `async_std::fs::DirEntry`
-/// doesn't provide a way to construct a `DirEntry` without opening directories
-/// by ambient paths.
+/// There is no `from_std` method, as `async_std::fs::DirEntry` doesn't provide
+/// a way to construct a `DirEntry` without opening directories by ambient
+/// paths.
 ///
 /// TODO: async
 pub struct DirEntry {

cap-async-std/src/fs/file.rs

@@ -26,9 +26,9 @@ use {
 ///
 /// This corresponds to [`async_std::fs::File`].
 ///
-/// Note that this `File` has no `open` or `create` methods. To open or create
-/// a file, you must first obtain a [`Dir`] containing the path, and then call
-/// [`Dir::open`] or [`Dir::create`].
+/// This `File` has no `open` or `create` methods. To open or create a file,
+/// first obtain a [`Dir`] containing the path, and then call [`Dir::open`] or
+/// [`Dir::create`].
 ///
 /// [`Dir`]: crate::fs::Dir
 /// [`Dir::open`]: crate::fs::Dir::open

cap-async-std/src/fs/read_dir.rs

@@ -6,9 +6,9 @@ use std::fmt;
 ///
 /// This corresponds to [`async_std::fs::ReadDir`].
 ///
-/// Note that there is no `from_std` method, as `async_std::fs::ReadDir`
-/// doesn't provide a way to construct a `ReadDir` without opening directories
-/// by ambient paths.
+/// There is no `from_std` method, as `async_std::fs::ReadDir` doesn't provide
+/// a way to construct a `ReadDir` without opening directories by ambient
+/// paths.
 pub struct ReadDir {
     pub(crate) inner: cap_primitives::fs::ReadDir,
 }

cap-async-std/src/fs_utf8/dir.rs

@@ -267,9 +267,9 @@ impl Dir {
 
     /// Remove the directory referenced by `self` and consume `self`.
     ///
-    /// Note that even though this implementation works in terms of handles
-    /// as much as possible, removal is not guaranteed to be atomic with
-    /// respect to a concurrent rename of the directory.
+    /// Even though this implementation works in terms of handles as much as
+    /// possible, removal is not guaranteed to be atomic with respect to a
+    /// concurrent rename of the directory.
     #[inline]
     pub async fn remove_open_dir(self) -> io::Result<()> {
         self.cap_std.remove_open_dir().await
@@ -278,9 +278,9 @@ impl Dir {
     /// Removes the directory referenced by `self`, after removing all its
     /// contents, and consume `self`. Use carefully!
     ///
-    /// Note that even though this implementation works in terms of handles
-    /// as much as possible, removal is not guaranteed to be atomic with
-    /// respect to a concurrent rename of the directory.
+    /// Even though this implementation works in terms of handles as much as
+    /// possible, removal is not guaranteed to be atomic with respect to a
+    /// concurrent rename of the directory.
     #[inline]
     pub async fn remove_open_dir_all(self) -> io::Result<()> {
         self.cap_std.remove_open_dir_all().await

cap-async-std/src/fs_utf8/dir_entry.rs

@@ -16,9 +16,9 @@ use std::{fmt, io};
 /// opening or removing the entry directly, which can be more efficient and
 /// convenient.
 ///
-/// Note that there is no `from_std` method, as `async_std::fs::DirEntry`
-/// doesn't provide a way to construct a `DirEntry` without opening directories
-/// by ambient paths.
+/// There is no `from_std` method, as `async_std::fs::DirEntry` doesn't provide
+/// a way to construct a `DirEntry` without opening directories by ambient
+/// paths.
 ///
 /// TODO: async
 pub struct DirEntry {

cap-async-std/src/fs_utf8/file.rs

@@ -25,9 +25,9 @@ use {
 ///
 /// This corresponds to [`async_std::fs::File`].
 ///
-/// Note that this `File` has no `open` or `create` methods. To open or create
-/// a file, you must first obtain a [`Dir`] containing the path, and then call
-/// [`Dir::open`] or [`Dir::create`].
+/// This `File` has no `open` or `create` methods. To open or create a file,
+/// first obtain a [`Dir`] containing the path, and then call [`Dir::open`] or
+/// [`Dir::create`].
 ///
 /// [`Dir`]: crate::fs::Dir
 /// [`Dir::open`]: crate::fs::Dir::open

cap-async-std/src/fs_utf8/read_dir.rs

@@ -5,9 +5,9 @@ use std::{fmt, io};
 ///
 /// This corresponds to [`async_std::fs::ReadDir`].
 ///
-/// Note that there is no `from_std` method, as `async_std::fs::ReadDir`
-/// doesn't provide a way to construct a `ReadDir` without opening directories
-/// by ambient paths.
+/// There is no `from_std` method, as `async_std::fs::ReadDir` doesn't provide
+/// a way to construct a `ReadDir` without opening directories by ambient
+/// paths.
 pub struct ReadDir {
     cap_std: crate::fs::ReadDir,
 }

cap-async-std/src/net/tcp_listener.rs

@@ -17,9 +17,9 @@ use {
 ///
 /// This corresponds to [`async_std::net::TcpListener`].
 ///
-/// Note that this `TcpListener` has no `bind` method. To bind it to a socket
-/// address, you must first obtain a [`Pool`] permitting the address, and
-/// then call [`Pool::bind_tcp_listener`].
+/// This `TcpListener` has no `bind` method. To bind it to a socket address,
+/// first obtain a [`Pool`] permitting the address, and then call
+/// [`Pool::bind_tcp_listener`].
 ///
 /// [`Pool`]: struct.Pool.html
 /// [`Pool::bind_tcp_listener`]: struct.Pool.html#method.bind_tcp_listener

cap-async-std/src/net/tcp_stream.rs

@@ -20,9 +20,9 @@ use {
 ///
 /// This corresponds to [`async_std::net::TcpStream`].
 ///
-/// Note that this `TcpStream` has no `connect` method. To create a
-/// `TcpStream`, you must first obtain a [`Pool`] permitting the address, and
-/// then call [`Pool::connect_tcp_stream`].
+/// This `TcpStream` has no `connect` method. To create a `TcpStream`, first
+/// obtain a [`Pool`] permitting the address, and then call
+/// [`Pool::connect_tcp_stream`].
 ///
 /// [`Pool`]: struct.Pool.html
 /// [`Pool::connect_tcp_stream`]: struct.Pool.html#method.connect_tcp_stream

cap-async-std/src/net/udp_socket.rs

@@ -17,17 +17,16 @@ use {
 ///
 /// This corresponds to [`async_std::net::UdpSocket`].
 ///
-/// Note that this `UdpSocket` has no `bind`, `connect`, or `send_to` methods.
-/// To create a `UdpSocket` bound to an address or to send a message to an
-/// address, you must first obtain a [`Pool`] permitting the address, and then
-/// call [`Pool::bind_udp_socket`], or [`Pool::connect_udp_socket`], or
+/// This `UdpSocket` has no `bind`, `connect`, or `send_to` methods. To create
+/// a `UdpSocket` bound to an address or to send a message to an address, first
+/// obtain a [`Pool`] permitting the address, and then call
+/// [`Pool::bind_udp_socket`], or [`Pool::connect_udp_socket`], or
 /// [`Pool::send_to_udp_socket_addr`].
 ///
 /// [`Pool`]: struct.Pool.html
 /// [`Pool::bind_udp_socket`]: struct.Pool.html#method.bind_udp_socket
 /// [`Pool::connect_udp_socket`]: struct.Pool.html#method.connect_udp_socket
-/// [`Pool::send_to_udp_socket_addr`]:
-/// struct.Pool.html#method.send_to_udp_socket_addr
+/// [`Pool::send_to_udp_socket_addr`]: struct.Pool.html#method.send_to_udp_socket_addr
 pub struct UdpSocket {
     pub(crate) std: net::UdpSocket,
 }

cap-async-std/src/os/unix/net/unix_datagram.rs

@@ -10,19 +10,16 @@ use std::fmt;
 ///
 /// This corresponds to [`async_std::os::unix::net::UnixDatagram`].
 ///
-/// Note that this `UnixDatagram` has no `bind`, `connect`, or `send_to`
-/// methods. To create a `UnixDatagram`,
-/// you must first obtain a [`Dir`] containing the path, and then call
-/// [`Dir::bind_unix_datagram`], [`Dir::connect_unix_datagram`], or
+/// This `UnixDatagram` has no `bind`, `connect`, or `send_to` methods. To
+/// create a `UnixDatagram`, first obtain a [`Dir`] containing the path, and
+/// then call [`Dir::bind_unix_datagram`], [`Dir::connect_unix_datagram`], or
 /// [`Dir::send_to_unix_datagram_addr`].
 ///
 /// [`async_std::os::unix::net::UnixDatagram`]: https://docs.rs/async-std/latest/async_std/os/unix/net/struct.UnixDatagram.html
 /// [`Dir`]: struct.Dir.html
-/// [`Dir::connect_unix_datagram`]:
-/// struct.Dir.html#method.connect_unix_datagram [`Dir::bind_unix_datagram`]:
-/// struct.Dir.html#method.bind_unix_datagram
-/// [`Dir::send_to_unix_datagram_addr`]:
-/// struct.Dir.html#method.send_to_unix_datagram_addr
+/// [`Dir::connect_unix_datagram`]: struct.Dir.html#method.connect_unix_datagram
+/// [`Dir::bind_unix_datagram`]: struct.Dir.html#method.bind_unix_datagram
+/// [`Dir::send_to_unix_datagram_addr`]: struct.Dir.html#method.send_to_unix_datagram_addr
 pub struct UnixDatagram {
     std: unix::net::UnixDatagram,
 }

cap-async-std/src/os/unix/net/unix_listener.rs

@@ -9,9 +9,9 @@ use std::fmt;
 ///
 /// This corresponds to [`async_std::os::unix::net::UnixListener`].
 ///
-/// Note that this `UnixListener` has no `bind` method. To bind it to a socket
-/// address, you must first obtain a [`Dir`] containing the path, and
-/// then call [`Dir::bind_unix_listener`].
+/// This `UnixListener` has no `bind` method. To bind it to a socket address,
+/// first obtain a [`Dir`] containing the path, and then call
+/// [`Dir::bind_unix_listener`].
 ///
 /// [`async_std::os::unix::net::UnixListener`]: https://docs.rs/async-std/latest/async_std/os/unix/net/struct.UnixListener.html
 /// [`Dir`]: struct.Dir.html

cap-async-std/src/os/unix/net/unix_stream.rs

@@ -12,9 +12,9 @@ use std::pin::Pin;
 ///
 /// This corresponds to [`async_std::os::unix::net::UnixStream`].
 ///
-/// Note that this `UnixStream` has no `connect` method. To create a
-/// `UnixStream`, you must first obtain a [`Dir`] containing the path, and then
-/// call [`Dir::connect_unix_stream`].
+/// This `UnixStream` has no `connect` method. To create a `UnixStream`, first
+/// obtain a [`Dir`] containing the path, and then call
+/// [`Dir::connect_unix_stream`].
 ///
 /// [`async_std::os::unix::net::UnixStream`]: https://docs.rs/async-std/latest/async_std/os/unix/net/struct.UnixStream.html
 /// [`Dir`]: struct.Dir.html

cap-primitives/src/fs/dir_entry.rs

@@ -18,9 +18,8 @@ use std::{fmt, fs, io};
 /// opening or removing the entry directly, which can be more efficient and
 /// convenient.
 ///
-/// Note that there is no `from_std` method, as `std::fs::DirEntry` doesn't
-/// provide a way to construct a `DirEntry` without opening directories by
-/// ambient paths.
+/// There is no `from_std` method, as `std::fs::DirEntry` doesn't provide a way
+/// to construct a `DirEntry` without opening directories by ambient paths.
 pub struct DirEntry {
     pub(crate) inner: DirEntryInner,
 }

cap-primitives/src/fs/follow_symlinks.rs

@@ -1,12 +1,11 @@
 /// Should symlinks be followed in the last component of a path?
 ///
-/// Note that this doesn't affect path components other than the last. So
-/// for example in "foo/bar/baz", if "foo" or "bar" are symlinks, they will
-/// always be followed. This enum value only determines whether "baz" is
-/// followed.
+/// This doesn't affect path components other than the last. So for example in
+/// "foo/bar/baz", if "foo" or "bar" are symlinks, they will always be
+/// followed. This enum value only determines whether "baz" is followed.
 ///
-/// Instead of passing bare `bool`s as parameters, pass a distinct
-/// enum so that the intent is clear.
+/// Instead of passing bare `bool`s as parameters, pass a distinct enum so that
+/// the intent is clear.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
 pub enum FollowSymlinks {

cap-primitives/src/fs/open_options.rs

@@ -4,9 +4,9 @@ use crate::fs::{FollowSymlinks, OpenOptionsExt};
 ///
 /// This corresponds to [`std::fs::OpenOptions`].
 ///
-/// Note that this `OpenOptions` has no `open` method. To open a file with
-/// an `OptionOptions`, you must first obtain a [`Dir`] containing the path,
-/// and then call [`Dir::open_with`].
+/// This `OpenOptions` has no `open` method. To open a file with an
+/// `OptionOptions`, first obtain a [`Dir`] containing the path, and then call
+/// [`Dir::open_with`].
 ///
 /// [`Dir`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html
 /// [`Dir::open_with`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html#method.open_with

cap-primitives/src/fs/read_dir.rs

@@ -47,9 +47,8 @@ pub(crate) fn read_dir_unchecked(
 ///
 /// This corresponds to [`std::fs::ReadDir`].
 ///
-/// Note that there is no `from_std` method, as `std::fs::ReadDir` doesn't
-/// provide a way to construct a `ReadDir` without opening directories by
-/// ambient paths.
+/// There is no `from_std` method, as `std::fs::ReadDir` doesn't provide a way
+/// to construct a `ReadDir` without opening directories by ambient paths.
 pub struct ReadDir {
     pub(crate) inner: ReadDirInner,
 }

cap-primitives/src/fs/via_parent/read_link.rs

@@ -6,12 +6,12 @@ use std::{fs, io};
 /// Implement `read_link` by `open`ing up the parent component of the path and
 /// then calling `read_link_unchecked` on the last component.
 ///
-/// Note that this technique doesn't work in all cases on Windows. In
-/// particular, a directory symlink such as `C:\Documents and Settings` may not
-/// grant any access other than what is needed to resolve the symlink, so
-/// `open_parent`'s technique of returning a relative path of `.` from that
-/// point doesn't work, because opening `.` within such a directory is denied.
-/// Consequently, we use a different implementation on Windows.
+/// This technique doesn't work in all cases on Windows. In particular, a
+/// directory symlink such as `C:\Documents and Settings` may not grant any
+/// access other than what is needed to resolve the symlink, so `open_parent`'s
+/// technique of returning a relative path of `.` from that point doesn't work,
+/// because opening `.` within such a directory is denied. Consequently, we use
+/// a different implementation on Windows.
 pub(crate) fn read_link(start: &fs::File, path: &Path) -> io::Result<PathBuf> {
     let start = MaybeOwnedFile::borrowed(start);
 

cap-primitives/src/time/instant.rs

@@ -6,9 +6,9 @@ use std::{fmt, time};
 ///
 /// This corresponds to [`std::time::Instant`].
 ///
-/// Note that this `Instant` has no `now` or `elapsed` methods. To obtain the
-/// current time or measure the duration to the current time, you must first
-/// obtain a [`MonotonicClock`], and then call [`MonotonicClock::now`] or
+/// This `Instant` has no `now` or `elapsed` methods. To obtain the current
+/// time or measure the duration to the current time, first obtain a
+/// [`MonotonicClock`], and then call [`MonotonicClock::now`] or
 /// [`MonotonicClock::elapsed`] instead.
 ///
 /// [`MonotonicClock`]: crate::time::MonotonicClock

cap-primitives/src/time/system_time.rs

@@ -7,9 +7,9 @@ use std::{fmt, time};
 ///
 /// This corresponds to [`std::time::SystemTime`].
 ///
-/// Note that this `SystemTime` has no `now`, `elapsed` methods. To obtain the
-/// current time or measure the duration to the current time, you must first
-/// obtain a [`SystemClock`], and then call [`SystemClock::now`] or
+/// This `SystemTime` has no `now`, `elapsed` methods. To obtain the current
+/// time or measure the duration to the current time, first obtain a
+/// [`SystemClock`], and then call [`SystemClock::now`] or
 /// [`SystemClock::elapsed`] instead. The `UNIX_EPOCH` constant is at
 /// [`SystemClock::UNIX_EPOCH`].
 ///

cap-primitives/src/windows/fs/create_dir_unchecked.rs

@@ -6,8 +6,8 @@ use std::{fs, io};
 /// *Unsandboxed* function similar to `create_dir`, but which does not perform
 /// sandboxing.
 ///
-/// Note that Windows doesn't have any extra flags in `DirOptions`, so the
-/// `options` parameter is ignored.
+/// Windows doesn't have any extra flags in `DirOptions`, so the `options`
+/// parameter is ignored.
 pub(crate) fn create_dir_unchecked(
     start: &fs::File,
     path: &Path,

cap-primitives/src/windows/fs/get_path.rs

@@ -5,9 +5,9 @@ use std::{fs, io};
 
 /// Calculates system path of `file`.
 ///
-/// Note that this function will automatically strip the extended
-/// prefix from the resultant path to allow for joining this resultant
-/// path with relative components.
+/// This function will automatically strip the extended prefix from the
+/// resultant path to allow for joining this resultant path with relative
+/// components.
 pub(crate) fn get_path(file: &fs::File) -> io::Result<PathBuf> {
     // get system path to the handle
     let path = winx::file::get_file_path(file)?;