Adding links for Atomics docs #29377

Author: projektir

src/libcore/sync/atomic.rs

@@ -15,27 +15,37 @@
 //! types.
 //!
 //! This module defines atomic versions of a select number of primitive
-//! types, including `AtomicBool`, `AtomicIsize`, and `AtomicUsize`.
+//! types, including [`AtomicBool`], [`AtomicIsize`], and [`AtomicUsize`].
 //! Atomic types present operations that, when used correctly, synchronize
 //! updates between threads.
 //!
-//! Each method takes an `Ordering` which represents the strength of
+//! [`AtomicBool`]: struct.AtomicBool.html
+//! [`AtomicIsize`]: struct.AtomicIsize.html
+//! [`AtomicUsize`]: struct.AtomicUsize.html
+//!
+//! Each method takes an [`Ordering`] which represents the strength of
 //! the memory barrier for that operation. These orderings are the
 //! same as [LLVM atomic orderings][1]. For more information see the [nomicon][2].
 //!
+//! [`Ordering`]: enum.Ordering.html
+//!
 //! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
 //! [2]: ../../../nomicon/atomics.html
 //!
-//! Atomic variables are safe to share between threads (they implement `Sync`)
+//! Atomic variables are safe to share between threads (they implement [`Sync`])
 //! but they do not themselves provide the mechanism for sharing and follow the
 //! [threading model](../../../std/thread/index.html#the-threading-model) of rust.
-//! The most common way to share an atomic variable is to put it into an `Arc` (an
+//! The most common way to share an atomic variable is to put it into an [`Arc`][arc] (an
 //! atomically-reference-counted shared pointer).
 //!
+//! [`Sync`]: ../../marker/trait.Sync.html
+//! [arc]: ../struct.Arc.html
+//!
 //! Most atomic types may be stored in static variables, initialized using
-//! the provided static initializers like `ATOMIC_BOOL_INIT`. Atomic statics
+//! the provided static initializers like [`ATOMIC_BOOL_INIT`]. Atomic statics
 //! are often used for lazy global initialization.
 //!
+//! [`ATOMIC_BOOL_INIT`]: constant.ATOMIC_BOOL_INIT.html
 //!
 //! # Examples
 //!
@@ -149,21 +159,26 @@ unsafe impl<T> Sync for AtomicPtr<T> {}
 #[derive(Copy, Clone, Debug)]
 pub enum Ordering {
     /// No ordering constraints, only atomic operations. Corresponds to LLVM's
-    /// `Monotonic` ordering.
+    /// [`Monotonic`][1] ordering.
+    /// [1]: http://llvm.org/docs/Atomics.html#monotonic
     #[stable(feature = "rust1", since = "1.0.0")]
     Relaxed,
     /// When coupled with a store, all previous writes become visible
-    /// to the other threads that perform a load with `Acquire` ordering
+    /// to the other threads that perform a load with [`Acquire`][1] ordering
     /// on the same value.
+    /// [1]: http://llvm.org/docs/Atomics.html#acquire
     #[stable(feature = "rust1", since = "1.0.0")]
     Release,
     /// When coupled with a load, all subsequent loads will see data
-    /// written before a store with `Release` ordering on the same value
+    /// written before a store with [`Release`][1] ordering on the same value
     /// in other threads.
+    /// [1]: http://llvm.org/docs/Atomics.html#release
     #[stable(feature = "rust1", since = "1.0.0")]
     Acquire,
-    /// When coupled with a load, uses `Acquire` ordering, and with a store
-    /// `Release` ordering.
+    /// When coupled with a load, uses [`Acquire`][1] ordering, and with a store
+    /// [`Release`][2] ordering.
+    /// [1]: http://llvm.org/docs/Atomics.html#acquire
+    /// [2]: http://llvm.org/docs/Atomics.html#release
     #[stable(feature = "rust1", since = "1.0.0")]
     AcqRel,
     /// Like `AcqRel` with the additional guarantee that all threads see all
@@ -176,7 +191,8 @@ pub enum Ordering {
     __Nonexhaustive,
 }
 
-/// An `AtomicBool` initialized to `false`.
+/// An [`AtomicBool`] initialized to `false`.
+/// [`AtomicBool`]: struct.AtomicBool.html
 #[cfg(target_has_atomic = "8")]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false);
@@ -241,7 +257,7 @@ impl AtomicBool {
 
     /// Loads a value from the bool.
     ///
-    /// `load` takes an [`Ordering`] argument which describes the memory ordering
+    /// `load()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// # Panics
@@ -250,7 +266,7 @@ impl AtomicBool {
     ///
     /// [`Ordering`]: enum.Ordering.html
     /// [`Release`]: enum.Ordering.html#variant.Release
-    /// [`AcqRel`]: enum.Ordering.html#variant.Release
+    /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
     ///
     /// # Examples
     ///
@@ -269,7 +285,7 @@ impl AtomicBool {
 
     /// Stores a value into the bool.
     ///
-    /// `store` takes an [`Ordering`] argument which describes the memory ordering
+    /// `store()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -287,7 +303,10 @@ impl AtomicBool {
     ///
     /// # Panics
     ///
-    /// Panics if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is [`Acquire`] or [`AcqRel`].
+    ///
+    /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+    /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn store(&self, val: bool, order: Ordering) {
@@ -298,7 +317,7 @@ impl AtomicBool {
 
     /// Stores a value into the bool, returning the old value.
     ///
-    /// `swap` takes an [`Ordering`] argument which describes the memory ordering
+    /// `swap()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -324,7 +343,7 @@ impl AtomicBool {
     /// The return value is always the previous value. If it is equal to `current`, then the value
     /// was updated.
     ///
-    /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
+    /// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
     /// ordering of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -356,7 +375,7 @@ impl AtomicBool {
     /// The return value is a result indicating whether the new value was written and containing
     /// the previous value. On success this value is guaranteed to be equal to `current`.
     ///
-    /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
+    /// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
     /// ordering of this operation. The first describes the required ordering if the
     /// operation succeeds while the second describes the required ordering when the
     /// operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and must
@@ -404,17 +423,18 @@ impl AtomicBool {
 
     /// Stores a value into the `bool` if the current value is the same as the `current` value.
     ///
-    /// Unlike `compare_exchange`, this function is allowed to spuriously fail even when the
+    /// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even when the
     /// comparison succeeds, which can result in more efficient code on some platforms. The
     /// return value is a result indicating whether the new value was written and containing the
     /// previous value.
     ///
-    /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
+    /// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
     /// ordering of this operation. The first describes the required ordering if the operation
     /// succeeds while the second describes the required ordering when the operation fails. The
     /// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
     /// weaker than the success ordering.
     ///
+    /// [`compare_exchange()`]: #method.compare_exchange
     /// [`Ordering`]: enum.Ordering.html
     /// [`Release`]: enum.Ordering.html#variant.Release
     /// [`AcqRel`]: enum.Ordering.html#variant.Release
@@ -645,7 +665,7 @@ impl<T> AtomicPtr<T> {
 
     /// Loads a value from the pointer.
     ///
-    /// `load` takes an [`Ordering`] argument which describes the memory ordering
+    /// `load()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// # Panics
@@ -674,7 +694,7 @@ impl<T> AtomicPtr<T> {
 
     /// Stores a value into the pointer.
     ///
-    /// `store` takes an [`Ordering`] argument which describes the memory ordering
+    /// `store()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -694,7 +714,11 @@ impl<T> AtomicPtr<T> {
     ///
     /// # Panics
     ///
-    /// Panics if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is [`Acquire`] or [`AcqRel`].
+    ///
+    /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+    /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
+    ///
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn store(&self, ptr: *mut T, order: Ordering) {
@@ -705,7 +729,7 @@ impl<T> AtomicPtr<T> {
 
     /// Stores a value into the pointer, returning the old value.
     ///
-    /// `swap` takes an [`Ordering`] argument which describes the memory ordering
+    /// `swap()` takes an [`Ordering`] argument which describes the memory ordering
     /// of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -733,7 +757,7 @@ impl<T> AtomicPtr<T> {
     /// The return value is always the previous value. If it is equal to `current`, then the value
     /// was updated.
     ///
-    /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
+    /// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
     /// ordering of this operation.
     ///
     /// [`Ordering`]: enum.Ordering.html
@@ -765,7 +789,7 @@ impl<T> AtomicPtr<T> {
     /// The return value is a result indicating whether the new value was written and containing
     /// the previous value. On success this value is guaranteed to be equal to `current`.
     ///
-    /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
+    /// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
     /// ordering of this operation. The first describes the required ordering if
     /// the operation succeeds while the second describes the required ordering when
     /// the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`]
@@ -812,18 +836,18 @@ impl<T> AtomicPtr<T> {
 
     /// Stores a value into the pointer if the current value is the same as the `current` value.
     ///
-    /// Unlike [`compare_exchange`], this function is allowed to spuriously fail even when the
+    /// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even when the
     /// comparison succeeds, which can result in more efficient code on some platforms. The
     /// return value is a result indicating whether the new value was written and containing the
     /// previous value.
     ///
-    /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
+    /// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
     /// ordering of this operation. The first describes the required ordering if the operation
     /// succeeds while the second describes the required ordering when the operation fails. The
     /// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
     /// weaker than the success ordering.
     ///
-    /// [`compare_exchange`]: #method.compare_exchange
+    /// [`compare_exchange()`]: #method.compare_exchange
     /// [`Ordering`]: enum.Ordering.html
     /// [`Release`]: enum.Ordering.html#variant.Release
     /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
@@ -962,7 +986,7 @@ macro_rules! atomic_int {
 
             /// Loads a value from the atomic integer.
             ///
-            /// `load` takes an [`Ordering`] argument which describes the memory ordering of this
+            /// `load()` takes an [`Ordering`] argument which describes the memory ordering of this
             /// operation.
             ///
             /// # Panics
@@ -990,7 +1014,7 @@ macro_rules! atomic_int {
 
             /// Stores a value into the atomic integer.
             ///
-            /// `store` takes an [`Ordering`] argument which describes the memory ordering of this
+            /// `store()` takes an [`Ordering`] argument which describes the memory ordering of this
             /// operation.
             ///
             /// [`Ordering`]: enum.Ordering.html
@@ -1008,7 +1032,11 @@ macro_rules! atomic_int {
             ///
             /// # Panics
             ///
-            /// Panics if `order` is `Acquire` or `AcqRel`.
+            /// Panics if `order` is [`Acquire`] or [`AcqRel`].
+            ///
+            /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+            /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
+            ///
             #[inline]
             #[$stable]
             pub fn store(&self, val: $int_type, order: Ordering) {
@@ -1017,7 +1045,7 @@ macro_rules! atomic_int {
 
             /// Stores a value into the atomic integer, returning the old value.
             ///
-            /// `swap` takes an [`Ordering`] argument which describes the memory ordering of this
+            /// `swap()` takes an [`Ordering`] argument which describes the memory ordering of this
             /// operation.
             ///
             /// [`Ordering`]: enum.Ordering.html
@@ -1043,7 +1071,7 @@ macro_rules! atomic_int {
             /// The return value is always the previous value. If it is equal to `current`, then the
             /// value was updated.
             ///
-            /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
+            /// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
             /// ordering of this operation.
             ///
             /// [`Ordering`]: enum.Ordering.html
@@ -1083,7 +1111,7 @@ macro_rules! atomic_int {
             /// containing the previous value. On success this value is guaranteed to be equal to
             /// `current`.
             ///
-            /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
+            /// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
             /// ordering of this operation. The first describes the required ordering if
             /// the operation succeeds while the second describes the required ordering when
             /// the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
@@ -1125,18 +1153,18 @@ macro_rules! atomic_int {
             /// Stores a value into the atomic integer if the current value is the same as the
             /// `current` value.
             ///
-            /// Unlike [`compare_exchange`], this function is allowed to spuriously fail even
+            /// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even
             /// when the comparison succeeds, which can result in more efficient code on some
             /// platforms. The return value is a result indicating whether the new value was
             /// written and containing the previous value.
             ///
-            /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
+            /// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
             /// ordering of this operation. The first describes the required ordering if the
             /// operation succeeds while the second describes the required ordering when the
             /// operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
             /// must be equivalent or weaker than the success ordering.
             ///
-            /// [`compare_exchange`]: #method.compare_exchange
+            /// [`compare_exchange()`]: #method.compare_exchange
             /// [`Ordering`]: enum.Ordering.html
             /// [`Release`]: enum.Ordering.html#variant.Release
             /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel