Merge pull request #405 from newAM/docs-update

docs: modernize intra doc links

.github/workflows/build.yml

@@ -188,13 +188,14 @@ jobs:
             ${{ runner.OS }}-build-${{ hashFiles('**/Cargo.lock') }}
             ${{ runner.OS }}-build-
 
-      - name: Install stable Rust with target (${{ matrix.target }})
-        uses: dtolnay/rust-toolchain@stable
+      - name: Install nightly Rust with target (${{ matrix.target }})
+        uses: dtolnay/rust-toolchain@nightly
         with:
           targets: ${{ matrix.target }}
 
-      - name: cargo doc
-        run: cargo doc --target=${{ matrix.target }} --features="ufmt serde defmt-03 mpmc_large portable-atomic-critical-section"
+      - name: cargo rustdoc
+        env: {"RUSTDOCFLAGS": "-D warnings --cfg docsrs"}
+        run: cargo rustdoc --target=${{ matrix.target }} --features="ufmt serde defmt-03 mpmc_large portable-atomic-critical-section"
 
   # Run cpass tests
   testcpass:

Cargo.toml

@@ -51,4 +51,7 @@ defmt = { version = ">=0.2.0,<0.4", optional = true }
 ufmt = "0.2"
 
 [package.metadata.docs.rs]
-all-features = true
+features = ["ufmt", "serde", "defmt-03", "mpmc_large", "portable-atomic-critical-section"]
+# for the pool module
+targets = ["i686-unknown-linux-gnu"]
+rustdoc-args = ["--cfg", "docsrs"]

cfail/Cargo.toml

@@ -5,8 +5,6 @@ name = "cfail"
 publish = false
 version = "0.1.0"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 heapless = { path = ".." }
 trybuild = "1.0.18"

src/binary_heap.rs

@@ -444,11 +444,8 @@ impl<'a, T> Hole<'a, T> {
 /// Structure wrapping a mutable reference to the greatest item on a
 /// `BinaryHeap`.
 ///
-/// This `struct` is created by the [`peek_mut`] method on [`BinaryHeap`]. See
-/// its documentation for more.
-///
-/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut
-/// [`BinaryHeap`]: struct.BinaryHeap.html
+/// This `struct` is created by [`BinaryHeap::peek_mut`].
+/// See its documentation for more.
 pub struct PeekMut<'a, T, K, const N: usize>
 where
     T: Ord,

src/indexmap.rs

@@ -12,10 +12,10 @@ use hash32::{BuildHasherDefault, FnvHasher};
 
 use crate::Vec;
 
-/// A [`heapless::IndexMap`](./struct.IndexMap.html) using the default FNV hasher
+/// A [`IndexMap`] using the default FNV hasher
 ///
 /// A list of all Methods and Traits available for `FnvIndexMap` can be found in
-/// the [`heapless::IndexMap`](./struct.IndexMap.html) documentation.
+/// the [`IndexMap`] documentation.
 ///
 /// # Examples
 /// ```
@@ -478,15 +478,16 @@ where
     }
 }
 
-/// Fixed capacity [`IndexMap`](https://docs.rs/indexmap/1/indexmap/map/struct.IndexMap.html)
+/// Fixed capacity [`IndexMap`](https://docs.rs/indexmap/2/indexmap/map/struct.IndexMap.html)
 ///
 /// Note that you cannot use `IndexMap` directly, since it is generic around the hashing algorithm
-/// in use. Pick a concrete instantiation like [`FnvIndexMap`](./type.FnvIndexMap.html) instead
+/// in use. Pick a concrete instantiation like [`FnvIndexMap`] instead
 /// or create your own.
 ///
 /// Note that the capacity of the `IndexMap` must be a power of 2.
 ///
 /// # Examples
+///
 /// Since `IndexMap` cannot be used directly, we're using its `FnvIndexMap` instantiation
 /// for this example.
 ///
@@ -904,7 +905,7 @@ where
         }
     }
 
-    /// Same as [`swap_remove`](struct.IndexMap.html#method.swap_remove)
+    /// Same as [`swap_remove`](Self::swap_remove)
     ///
     /// Computes in **O(1)** time (average).
     ///

src/indexset.rs

@@ -7,10 +7,10 @@ use core::{
 };
 use hash32::{BuildHasherDefault, FnvHasher};
 
-/// A [`heapless::IndexSet`](./struct.IndexSet.html) using the
+/// A [`IndexSet`] using the
 /// default FNV hasher.
 /// A list of all Methods and Traits available for `FnvIndexSet` can be found in
-/// the [`heapless::IndexSet`](./struct.IndexSet.html) documentation.
+/// the [`IndexSet`] documentation.
 ///
 /// # Examples
 /// ```
@@ -41,10 +41,10 @@ use hash32::{BuildHasherDefault, FnvHasher};
 /// ```
 pub type FnvIndexSet<T, const N: usize> = IndexSet<T, BuildHasherDefault<FnvHasher>, N>;
 
-/// Fixed capacity [`IndexSet`](https://docs.rs/indexmap/1/indexmap/set/struct.IndexSet.html).
+/// Fixed capacity [`IndexSet`](https://docs.rs/indexmap/2/indexmap/set/struct.IndexSet.html).
 ///
 /// Note that you cannot use `IndexSet` directly, since it is generic around the hashing algorithm
-/// in use. Pick a concrete instantiation like [`FnvIndexSet`](./type.FnvIndexSet.html) instead
+/// in use. Pick a concrete instantiation like [`FnvIndexSet`] instead
 /// or create your own.
 ///
 /// Note that the capacity of the `IndexSet` must be a power of 2.

src/lib.rs

@@ -43,19 +43,26 @@
 //!
 //! List of currently implemented data structures:
 //!
-//! - [`Arc`](pool/arc/index.html) -- like `std::sync::Arc` but backed by a lock-free memory pool
-//! rather than `#[global_allocator]`
-//! - [`Box`](pool/boxed/index.html) -- like `std::boxed::Box` but backed by a lock-free memory pool
-//! rather than `#[global_allocator]`
-//! - [`BinaryHeap`](binary_heap/struct.BinaryHeap.html) -- priority queue
-//! - [`IndexMap`](struct.IndexMap.html) -- hash table
-//! - [`IndexSet`](struct.IndexSet.html) -- hash set
-//! - [`LinearMap`](struct.LinearMap.html)
-//! - [`Object`](pool/object/index.html) -- objects managed by an object pool
-//! - [`String`](struct.String.html)
-//! - [`Vec`](struct.Vec.html)
-//! - [`mpmc::Q*`](mpmc/index.html) -- multiple producer multiple consumer lock-free queue
-//! - [`spsc::Queue`](spsc/struct.Queue.html) -- single producer single consumer lock-free queue
+#![cfg_attr(
+    any(arm_llsc, target_arch = "x86"),
+    doc = "- [`Arc`](pool::arc::Arc) -- like `std::sync::Arc` but backed by a lock-free memory pool rather than `#[global_allocator]`"
+)]
+#![cfg_attr(
+    any(arm_llsc, target_arch = "x86"),
+    doc = "- [`Box`](pool::boxed::Box) -- like `std::boxed::Box` but backed by a lock-free memory pool rather than `#[global_allocator]`"
+)]
+//! - [`BinaryHeap`] -- priority queue
+//! - [`IndexMap`] -- hash table
+//! - [`IndexSet`] -- hash set
+//! - [`LinearMap`]
+#![cfg_attr(
+    any(arm_llsc, target_arch = "x86"),
+    doc = "- [`Object`](pool::object::Object) -- objects managed by an object pool"
+)]
+//! - [`String`]
+//! - [`Vec`]
+//! - [`mpmc::Q*`](mpmc) -- multiple producer multiple consumer lock-free queue
+//! - [`spsc::Queue`] -- single producer single consumer lock-free queue
 //!
 //! # Optional Features
 //!
@@ -72,7 +79,7 @@
 //!
 //! In other words, changes in the Rust version requirement of this crate are not considered semver
 //! breaking change and may occur in patch version releases.
-
+#![cfg_attr(docsrs, feature(doc_cfg), feature(doc_auto_cfg))]
 #![cfg_attr(not(test), no_std)]
 #![deny(missing_docs)]
 #![deny(warnings)]

src/pool/arc.rs

@@ -79,7 +79,7 @@ use super::treiber::{NonNullPtr, Stack, UnionNode};
 
 /// Creates a new `ArcPool` singleton with the given `$name` that manages the specified `$data_type`
 ///
-/// For more extensive documentation see the [module level documentation](pool/arc/index.html)
+/// For more extensive documentation see the [module level documentation](crate::pool::arc)
 #[macro_export]
 macro_rules! arc_pool {
     ($name:ident: $data_type:ty) => {

src/pool/boxed.rs

@@ -90,7 +90,7 @@ use super::treiber::{NonNullPtr, Stack, UnionNode};
 
 /// Creates a new `BoxPool` singleton with the given `$name` that manages the specified `$data_type`
 ///
-/// For more extensive documentation see the [module level documentation](pool/boxed/index.html)
+/// For more extensive documentation see the [module level documentation](crate::pool::boxed)
 #[macro_export]
 macro_rules! box_pool {
     ($name:ident: $data_type:ty) => {

src/pool/object.rs

@@ -78,7 +78,7 @@ use super::treiber::{AtomicPtr, NonNullPtr, Stack, StructNode};
 /// Creates a new `ObjectPool` singleton with the given `$name` that manages the specified
 /// `$data_type`
 ///
-/// For more extensive documentation see the [module level documentation](pool/object/index.html)
+/// For more extensive documentation see the [module level documentation](crate::pool::object)
 #[macro_export]
 macro_rules! object_pool {
     ($name:ident: $data_type:ty) => {

src/string.rs

@@ -232,8 +232,6 @@ impl<const N: usize> String<N> {
 
     /// Appends the given [`char`] to the end of this `String`.
     ///
-    /// [`char`]: ../../std/primitive.char.html
-    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -274,8 +272,6 @@ impl<const N: usize> String<N> {
     ///
     /// Panics if `new_len` does not lie on a [`char`] boundary.
     ///
-    /// [`char`]: ../../std/primitive.char.html
-    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -302,8 +298,6 @@ impl<const N: usize> String<N> {
     ///
     /// Returns [`None`] if this `String` is empty.
     ///
-    /// [`None`]: ../../std/option/enum.Option.html#variant.None
-    ///
     /// # Examples
     ///
     /// Basic usage:

src/vec.rs

@@ -56,7 +56,7 @@ impl<T, const N: usize> Vec<T, N> {
     /// // allocate the vector in a static variable
     /// static mut X: Vec<u8, 16> = Vec::new();
     /// ```
-    /// `Vec` `const` constructor; wrap the returned value in [`Vec`](../struct.Vec.html)
+    /// `Vec` `const` constructor; wrap the returned value in [`Vec`].
     pub const fn new() -> Self {
         Self {
             len: 0,
@@ -304,7 +304,7 @@ impl<T, const N: usize> Vec<T, N> {
     /// difference, with each additional slot filled with value. If
     /// new_len is less than len, the Vec is simply truncated.
     ///
-    /// See also [`resize_default`](struct.Vec.html#method.resize_default).
+    /// See also [`resize_default`](Self::resize_default).
     pub fn resize(&mut self, new_len: usize, value: T) -> Result<(), ()>
     where
         T: Clone,
@@ -330,7 +330,7 @@ impl<T, const N: usize> Vec<T, N> {
     /// difference, with each additional slot filled with `Default::default()`.
     /// If `new_len` is less than `len`, the `Vec` is simply truncated.
     ///
-    /// See also [`resize`](struct.Vec.html#method.resize).
+    /// See also [`resize`](Self::resize).
     pub fn resize_default(&mut self, new_len: usize) -> Result<(), ()>
     where
         T: Clone + Default,
@@ -345,17 +345,17 @@ impl<T, const N: usize> Vec<T, N> {
     /// is done using one of the safe operations instead, such as
     /// [`truncate`], [`resize`], [`extend`], or [`clear`].
     ///
-    /// [`truncate`]: #method.truncate
-    /// [`resize`]: #method.resize
-    /// [`extend`]: https://doc.rust-lang.org/stable/core/iter/trait.Extend.html#tymethod.extend
-    /// [`clear`]: #method.clear
+    /// [`truncate`]: Self::truncate
+    /// [`resize`]: Self::resize
+    /// [`extend`]: core::iter::Extend
+    /// [`clear`]: Self::clear
     ///
     /// # Safety
     ///
     /// - `new_len` must be less than or equal to [`capacity()`].
     /// - The elements at `old_len..new_len` must be initialized.
     ///
-    /// [`capacity()`]: #method.capacity
+    /// [`capacity()`]: Self::capacity
     ///
     /// # Examples
     ///
@@ -925,9 +925,6 @@ impl<T, const N: usize> FromIterator<T> for Vec<T, N> {
 /// An iterator that moves out of an [`Vec`][`Vec`].
 ///
 /// This struct is created by calling the `into_iter` method on [`Vec`][`Vec`].
-///
-/// [`Vec`]: (https://doc.rust-lang.org/std/vec/struct.Vec.html)
-///
 pub struct IntoIter<T, const N: usize> {
     vec: Vec<T, N>,
     next: usize,