Improve docs for crossbeam-utils

* Document some panics and errors
* Use intra-doc links
* Minor doc improvements

crossbeam-utils/src/atomic/atomic_cell.rs

@@ -24,10 +24,10 @@ use const_fn::const_fn;
 ///
 /// Atomic loads use the [`Acquire`] ordering and atomic stores use the [`Release`] ordering.
 ///
-/// [`Cell`]: https://doc.rust-lang.org/std/cell/struct.Cell.html
-/// [`AtomicCell::<T>::is_lock_free()`]: struct.AtomicCell.html#method.is_lock_free
-/// [`Acquire`]: https://doc.rust-lang.org/std/sync/atomic/enum.Ordering.html#variant.Acquire
-/// [`Release`]: https://doc.rust-lang.org/std/sync/atomic/enum.Ordering.html#variant.Release
+/// [`Cell`]: std::cell::Cell
+/// [`AtomicCell::<T>::is_lock_free()`]: AtomicCell::is_lock_free
+/// [`Acquire`]: std::sync::atomic::Ordering::Acquire
+/// [`Release`]: std::sync::atomic::Ordering::Release
 #[repr(transparent)]
 pub struct AtomicCell<T: ?Sized> {
     /// The inner value.
@@ -62,7 +62,7 @@ impl<T> AtomicCell<T> {
         }
     }
 
-    /// Unwraps the atomic cell and returns its inner value.
+    /// Consumes the atomic and returns the contained value.
     ///
     /// # Examples
     ///
@@ -190,7 +190,7 @@ impl<T: Default> AtomicCell<T> {
 }
 
 impl<T: Copy> AtomicCell<T> {
-    /// Loads a value.
+    /// Loads a value from the atomic cell.
     ///
     /// # Examples
     ///

crossbeam-utils/src/backoff.rs

@@ -72,11 +72,11 @@ const YIELD_LIMIT: u32 = 10;
 /// }
 /// ```
 ///
-/// [`is_completed`]: struct.Backoff.html#method.is_completed
-/// [`std::thread::park()`]: https://doc.rust-lang.org/std/thread/fn.park.html
-/// [`Condvar`]: https://doc.rust-lang.org/std/sync/struct.Condvar.html
-/// [`AtomicBool`]: https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html
-/// [`unpark()`]: https://doc.rust-lang.org/std/thread/struct.Thread.html#method.unpark
+/// [`is_completed`]: Backoff::is_completed
+/// [`std::thread::park()`]: std::thread::park
+/// [`Condvar`]: std::sync::Condvar
+/// [`AtomicBool`]: std::sync::atomic::AtomicBool
+/// [`unpark()`]: std::thread::Thread::unpark
 pub struct Backoff {
     step: Cell<u32>,
 }
@@ -165,8 +165,8 @@ impl Backoff {
     /// If possible, use [`is_completed`] to check when it is advised to stop using backoff and
     /// block the current thread using a different synchronization mechanism instead.
     ///
-    /// [`spin`]: struct.Backoff.html#method.spin
-    /// [`is_completed`]: struct.Backoff.html#method.is_completed
+    /// [`spin`]: Backoff::spin
+    /// [`is_completed`]: Backoff::is_completed
     ///
     /// # Examples
     ///
@@ -200,7 +200,7 @@ impl Backoff {
     /// assert_eq!(ready.load(SeqCst), true);
     /// ```
     ///
-    /// [`AtomicBool`]: https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html
+    /// [`AtomicBool`]: std::sync::atomic::AtomicBool
     #[inline]
     pub fn snooze(&self) {
         if self.step.get() <= SPIN_LIMIT {
@@ -262,7 +262,7 @@ impl Backoff {
     /// assert_eq!(ready.load(SeqCst), true);
     /// ```
     ///
-    /// [`AtomicBool`]: https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html
+    /// [`AtomicBool`]: std::sync::atomic::AtomicBool
     #[inline]
     pub fn is_completed(&self) -> bool {
         self.step.get() > YIELD_LIMIT

crossbeam-utils/src/sync/parker.rs

@@ -48,9 +48,9 @@ use std::time::Duration;
 /// p.park();
 /// ```
 ///
-/// [`park`]: struct.Parker.html#method.park
-/// [`park_timeout`]: struct.Parker.html#method.park_timeout
-/// [`unpark`]: struct.Unparker.html#method.unpark
+/// [`park`]: Parker::park
+/// [`park_timeout`]: Parker::park_timeout
+/// [`unpark`]: Unparker::unpark
 pub struct Parker {
     unparker: Unparker,
     _marker: PhantomData<*const ()>,
@@ -149,10 +149,8 @@ impl Parker {
     /// p.park();
     /// ```
     ///
-    /// [`park`]: struct.Parker.html#method.park
-    /// [`park_timeout`]: struct.Parker.html#method.park_timeout
-    ///
-    /// [`Unparker`]: struct.Unparker.html
+    /// [`park`]: Parker::park
+    /// [`park_timeout`]: Parker::park_timeout
     pub fn unparker(&self) -> &Unparker {
         &self.unparker
     }
@@ -177,8 +175,6 @@ impl Parker {
     ///
     /// This method is safe to use only with pointers returned by [`Parker::into_raw`].
     ///
-    /// [`Parker::into_raw`]: struct.Parker.html#method.into_raw
-    ///
     /// # Examples
     ///
     /// ```
@@ -203,8 +199,6 @@ impl fmt::Debug for Parker {
 }
 
 /// Unparks a thread parked by the associated [`Parker`].
-///
-/// [`Parker`]: struct.Parker.html
 pub struct Unparker {
     inner: Arc<Inner>,
 }
@@ -238,8 +232,8 @@ impl Unparker {
     /// p.park();
     /// ```
     ///
-    /// [`park`]: struct.Parker.html#method.park
-    /// [`park_timeout`]: struct.Parker.html#method.park_timeout
+    /// [`park`]: Parker::park
+    /// [`park_timeout`]: Parker::park_timeout
     pub fn unpark(&self) {
         self.inner.unpark()
     }
@@ -265,8 +259,6 @@ impl Unparker {
     ///
     /// This method is safe to use only with pointers returned by [`Unparker::into_raw`].
     ///
-    /// [`Unparker::into_raw`]: struct.Unparker.html#method.into_raw
-    ///
     /// # Examples
     ///
     /// ```

crossbeam-utils/src/sync/sharded_lock.rs

@@ -72,7 +72,7 @@ struct Shard {
 /// } // Write lock is dropped here.
 /// ```
 ///
-/// [`RwLock`]: https://doc.rust-lang.org/std/sync/struct.RwLock.html
+/// [`RwLock`]: std::sync::RwLock
 pub struct ShardedLock<T: ?Sized> {
     /// A list of locks protecting the internal data.
     shards: Box<[CachePadded<Shard>]>,
@@ -114,6 +114,8 @@ impl<T> ShardedLock<T> {
 
     /// Consumes this lock, returning the underlying data.
     ///
+    /// # Errors
+    ///
     /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
     /// operation panics.
     ///
@@ -171,6 +173,8 @@ impl<T: ?Sized> ShardedLock<T> {
     ///
     /// Since this call borrows the lock mutably, no actual locking needs to take place.
     ///
+    /// # Errors
+    ///
     /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
     /// operation panics.
     ///
@@ -201,6 +205,8 @@ impl<T: ?Sized> ShardedLock<T> {
     /// provide any guarantees with respect to the ordering of whether contentious readers or
     /// writers will acquire the lock first.
     ///
+    /// # Errors
+    ///
     /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
     /// operation panics.
     ///
@@ -249,6 +255,15 @@ impl<T: ?Sized> ShardedLock<T> {
     ///
     /// Returns a guard which will release the shared access when dropped.
     ///
+    /// # Errors
+    ///
+    /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
+    /// operation panics.
+    ///
+    /// # Panics
+    ///
+    /// This method might panic when called if the lock is already held by the current thread.
+    ///
     /// # Examples
     ///
     /// ```
@@ -294,6 +309,8 @@ impl<T: ?Sized> ShardedLock<T> {
     /// not provide any guarantees with respect to the ordering of whether contentious readers or
     /// writers will acquire the lock first.
     ///
+    /// # Errors
+    ///
     /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
     /// operation panics.
     ///
@@ -368,6 +385,15 @@ impl<T: ?Sized> ShardedLock<T> {
     ///
     /// Returns a guard which will release the exclusive access when dropped.
     ///
+    /// # Errors
+    ///
+    /// This method will return an error if the lock is poisoned. A lock gets poisoned when a write
+    /// operation panics.
+    ///
+    /// # Panics
+    ///
+    /// This method might panic when called if the lock is already held by the current thread.
+    ///
     /// # Examples
     ///
     /// ```

crossbeam-utils/src/sync/wait_group.rs

@@ -10,13 +10,13 @@ use std::sync::{Arc, Condvar, Mutex};
 ///
 /// `WaitGroup` is very similar to [`Barrier`], but there are a few differences:
 ///
-/// * `Barrier` needs to know the number of threads at construction, while `WaitGroup` is cloned to
+/// * [`Barrier`] needs to know the number of threads at construction, while `WaitGroup` is cloned to
 ///   register more threads.
 ///
-/// * A `Barrier` can be reused even after all threads have synchronized, while a `WaitGroup`
+/// * A [`Barrier`] can be reused even after all threads have synchronized, while a `WaitGroup`
 ///   synchronizes threads only once.
 ///
-/// * All threads wait for others to reach the `Barrier`. With `WaitGroup`, each thread can choose
+/// * All threads wait for others to reach the [`Barrier`]. With `WaitGroup`, each thread can choose
 ///   to either wait for other threads or to continue without blocking.
 ///
 /// # Examples
@@ -44,7 +44,7 @@ use std::sync::{Arc, Condvar, Mutex};
 /// wg.wait();
 /// ```
 ///
-/// [`Barrier`]: https://doc.rust-lang.org/std/sync/struct.Barrier.html
+/// [`Barrier`]: std::sync::Barrier
 pub struct WaitGroup {
     inner: Arc<Inner>,
 }

crossbeam-utils/src/thread.rs

@@ -111,7 +111,7 @@
 //! }).unwrap();
 //! ```
 //!
-//! [`std::thread::spawn`]: https://doc.rust-lang.org/std/thread/fn.spawn.html
+//! [`std::thread::spawn`]: std::thread::spawn
 
 use std::fmt;
 use std::io;
@@ -215,9 +215,18 @@ impl<'env> Scope<'env> {
     /// The scoped thread is passed a reference to this scope as an argument, which can be used for
     /// spawning nested threads.
     ///
-    /// The returned handle can be used to manually join the thread before the scope exits.
+    /// The returned [handle](ScopedJoinHandle) can be used to manually
+    /// [join](ScopedJoinHandle::join) the thread before the scope exits.
+    ///
+    /// This will create a thread using default parameters of [`ScopedThreadBuilder`], if you want to specify the
+    /// stack size or the name of the thread, use this API instead.
+    ///
+    /// [`spawn`]: std::thread::spawn
+    ///
+    /// # Panics
     ///
-    /// [`spawn`]: https://doc.rust-lang.org/std/thread/fn.spawn.html
+    /// Panics if the OS fails to create a thread; use [`ScopedThreadBuilder::spawn`]
+    /// to recover from such errors.
     ///
     /// # Examples
     ///
@@ -241,7 +250,9 @@ impl<'env> Scope<'env> {
         F: Send + 'env,
         T: Send + 'env,
     {
-        self.builder().spawn(f).unwrap()
+        self.builder()
+            .spawn(f)
+            .expect("failed to spawn scoped thread")
     }
 
     /// Creates a builder that can configure a thread before spawning.
@@ -297,13 +308,12 @@ impl fmt::Debug for Scope<'_> {
 /// }).unwrap();
 /// ```
 ///
-/// [`name`]: struct.ScopedThreadBuilder.html#method.name
-/// [`stack_size`]: struct.ScopedThreadBuilder.html#method.stack_size
-/// [`spawn`]: struct.ScopedThreadBuilder.html#method.spawn
-/// [`Scope::spawn`]: struct.Scope.html#method.spawn
-/// [`io::Result`]: https://doc.rust-lang.org/std/io/type.Result.html
-/// [naming-threads]: https://doc.rust-lang.org/std/thread/index.html#naming-threads
-/// [stack-size]: https://doc.rust-lang.org/std/thread/index.html#stack-size
+/// [`name`]: ScopedThreadBuilder::name
+/// [`stack_size`]: ScopedThreadBuilder::stack_size
+/// [`spawn`]: ScopedThreadBuilder::spawn
+/// [`io::Result`]: std::io::Result
+/// [naming-threads]: std::thread#naming-threads
+/// [stack-size]: std::thread#stack-size
 #[derive(Debug)]
 pub struct ScopedThreadBuilder<'scope, 'env> {
     scope: &'scope Scope<'env>,
@@ -313,8 +323,9 @@ pub struct ScopedThreadBuilder<'scope, 'env> {
 impl<'scope, 'env> ScopedThreadBuilder<'scope, 'env> {
     /// Sets the name for the new thread.
     ///
-    /// The name must not contain null bytes. For more information about named threads, see
-    /// [here][naming-threads].
+    /// The name must not contain null bytes (`\0`).
+    ///
+    /// For more information about named threads, see [here][naming-threads].
     ///
     /// # Examples
     ///
@@ -330,7 +341,7 @@ impl<'scope, 'env> ScopedThreadBuilder<'scope, 'env> {
     /// }).unwrap();
     /// ```
     ///
-    /// [naming-threads]: https://doc.rust-lang.org/std/thread/index.html#naming-threads
+    /// [naming-threads]: std::thread#naming-threads
     pub fn name(mut self, name: String) -> ScopedThreadBuilder<'scope, 'env> {
         self.builder = self.builder.name(name);
         self
@@ -340,6 +351,8 @@ impl<'scope, 'env> ScopedThreadBuilder<'scope, 'env> {
     ///
     /// The stack size is measured in bytes.
     ///
+    /// For more information about the stack size for threads, see [here][stack-size].
+    ///
     /// # Examples
     ///
     /// ```
@@ -352,6 +365,8 @@ impl<'scope, 'env> ScopedThreadBuilder<'scope, 'env> {
     ///         .unwrap();
     /// }).unwrap();
     /// ```
+    ///
+    /// [stack-size]: std::thread#stack-size
     pub fn stack_size(mut self, size: usize) -> ScopedThreadBuilder<'scope, 'env> {
         self.builder = self.builder.stack_size(size);
         self
@@ -364,6 +379,18 @@ impl<'scope, 'env> ScopedThreadBuilder<'scope, 'env> {
     ///
     /// The returned handle can be used to manually join the thread before the scope exits.
     ///
+    /// # Errors
+    ///
+    /// Unlike the [`Scope::spawn`] method, this method yields an
+    /// [`io::Result`] to capture any failure to create the thread at
+    /// the OS level.
+    ///
+    /// [`io::Result`]: std::io::Result
+    ///
+    /// # Panics
+    ///
+    /// Panics if a thread name was set and it contained null bytes.
+    ///
     /// # Examples
     ///
     /// ```
@@ -445,6 +472,9 @@ unsafe impl<T> Send for ScopedJoinHandle<'_, T> {}
 unsafe impl<T> Sync for ScopedJoinHandle<'_, T> {}
 
 /// A handle that can be used to join its scoped thread.
+///
+/// This struct is created by the [`Scope::spawn`] method and the
+/// [`ScopedThreadBuilder::spawn`] method.
 pub struct ScopedJoinHandle<'scope, T> {
     /// A join handle to the spawned thread.
     handle: SharedOption<thread::JoinHandle<()>>,