From 4799f8ce107f27a6d6c1d1dd4f081c762b751536 Mon Sep 17 00:00:00 2001 From: Alex Martens Date: Tue, 31 Oct 2023 20:38:29 -0700 Subject: [PATCH] docs: modernize intra doc links --- .github/workflows/build.yml | 9 +++++---- Cargo.toml | 5 ++++- cfail/Cargo.toml | 2 -- src/binary_heap.rs | 7 ++----- src/indexmap.rs | 11 ++++++----- src/indexset.rs | 8 ++++---- src/lib.rs | 35 +++++++++++++++++++++-------------- src/pool/arc.rs | 2 +- src/pool/boxed.rs | 2 +- src/pool/object.rs | 2 +- src/string.rs | 6 ------ src/vec.rs | 19 ++++++++----------- 12 files changed, 53 insertions(+), 55 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5d2d1cbe45..1e3b0ca07c 100644 --- a/.github/workflows/build.yml +++ b/.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: diff --git a/Cargo.toml b/Cargo.toml index 7a4a222758..025482021b 100644 --- a/Cargo.toml +++ b/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"] diff --git a/cfail/Cargo.toml b/cfail/Cargo.toml index e93f5ca127..96009c9052 100644 --- a/cfail/Cargo.toml +++ b/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" diff --git a/src/binary_heap.rs b/src/binary_heap.rs index d1fbe7d997..ace9863e2d 100644 --- a/src/binary_heap.rs +++ b/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, diff --git a/src/indexmap.rs b/src/indexmap.rs index 8e14ce9c42..dffb10a452 100644 --- a/src/indexmap.rs +++ b/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). /// diff --git a/src/indexset.rs b/src/indexset.rs index 2d5031a19a..03e4f2df3c 100644 --- a/src/indexset.rs +++ b/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 = IndexSet, 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. diff --git a/src/lib.rs b/src/lib.rs index 130120908d..94e3a7fdc6 100644 --- a/src/lib.rs +++ b/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)] diff --git a/src/pool/arc.rs b/src/pool/arc.rs index f514633deb..a5c5f2cef9 100644 --- a/src/pool/arc.rs +++ b/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) => { diff --git a/src/pool/boxed.rs b/src/pool/boxed.rs index 86a39e751f..cb92a3efa3 100644 --- a/src/pool/boxed.rs +++ b/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) => { diff --git a/src/pool/object.rs b/src/pool/object.rs index 0630645a85..a12d69bfed 100644 --- a/src/pool/object.rs +++ b/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) => { diff --git a/src/string.rs b/src/string.rs index 8dc98ed79c..086f21e80d 100644 --- a/src/string.rs +++ b/src/string.rs @@ -232,8 +232,6 @@ impl String { /// Appends the given [`char`] to the end of this `String`. /// - /// [`char`]: ../../std/primitive.char.html - /// /// # Examples /// /// Basic usage: @@ -274,8 +272,6 @@ impl String { /// /// Panics if `new_len` does not lie on a [`char`] boundary. /// - /// [`char`]: ../../std/primitive.char.html - /// /// # Examples /// /// Basic usage: @@ -302,8 +298,6 @@ impl String { /// /// Returns [`None`] if this `String` is empty. /// - /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// /// # Examples /// /// Basic usage: diff --git a/src/vec.rs b/src/vec.rs index 0dc25f1dd1..9705150e24 100644 --- a/src/vec.rs +++ b/src/vec.rs @@ -56,7 +56,7 @@ impl Vec { /// // allocate the vector in a static variable /// static mut X: Vec = 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 { // Const assert N >= 0 crate::sealed::greater_than_eq_0::(); @@ -307,7 +307,7 @@ impl Vec { /// 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, @@ -333,7 +333,7 @@ impl Vec { /// 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, @@ -348,17 +348,17 @@ impl Vec { /// 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 /// @@ -928,9 +928,6 @@ impl FromIterator for Vec { /// 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 { vec: Vec, next: usize,