Merge pull request #390 from robertknight/backtick-docs

Enclose linked identifiers in backticks in API docs

rten-examples/src/detr.rs

@@ -83,7 +83,7 @@ Options:
     Ok(args)
 }
 
-/// Resolve the min/max size to use as inputs for [rescaled_size] based on
+/// Resolve the min/max size to use as inputs for [`rescaled_size`] based on
 /// the min/max CLI args and defaults for the model configuration.
 fn resolve_min_max_size(
     min: Option<u32>,

rten-imageproc/src/contours.rs

@@ -64,7 +64,7 @@ fn find_nonzero_neighbor<
     None
 }
 
-/// Specifies which contours to extract from a mask in [find_contours].
+/// Specifies which contours to extract from a mask in [`find_contours`].
 pub enum RetrievalMode {
     /// Get only the outer-most contours.
     External,

rten-imageproc/src/drawing.rs

@@ -214,7 +214,7 @@ pub fn draw_polygon<T: Copy>(
     }
 }
 
-/// Tracks data about an edge in a polygon being traversed by [FillIter].
+/// Tracks data about an edge in a polygon being traversed by [`FillIter`].
 #[derive(Clone, Copy, Debug)]
 struct Edge {
     /// Y coordinate where this edge starts
@@ -244,7 +244,7 @@ struct Edge {
 }
 
 /// Iterator over coordinates of pixels that fill a polygon. See
-/// [Polygon::fill_iter] for notes on how this iterator determines which
+/// [`Polygon::fill_iter`] for notes on how this iterator determines which
 /// pixels are inside the polygon.
 ///
 /// The implementation follows <https://www.jagregory.com/abrash-black-book/#filling-arbitrary-polygons>.
@@ -434,7 +434,7 @@ impl<'a, T: Copy + Default> Painter<'a, T> {
         self.saved_states.push(self.state);
     }
 
-    /// Pop and apply a drawing style from the stack created with [Painter::save].
+    /// Pop and apply a drawing style from the stack created with [`Painter::save`].
     pub fn restore(&mut self) {
         if let Some(state) = self.saved_states.pop() {
             self.state = state;
@@ -445,7 +445,7 @@ impl<'a, T: Copy + Default> Painter<'a, T> {
     /// style.
     ///
     /// This avoids the need to manually save and restore state with
-    /// [Painter::save] and [Painter::restore].
+    /// [`Painter::save`] and [`Painter::restore`].
     pub fn with_save<F: Fn(&mut Self)>(&mut self, f: F) {
         self.save();
         f(self);

rten-imageproc/src/poly_algos.rs

@@ -136,7 +136,7 @@ pub fn simplify_polyline(points: &[PointF], epsilon: f32) -> Vec<PointF> {
 
 /// Return a simplified version of the polygon defined by `points`.
 ///
-/// This is very similar to [simplify_polyline] except that the input is
+/// This is very similar to [`simplify_polyline`] except that the input is
 /// treated as a polygon where the last point implicitly connects to the first
 /// point to close the shape.
 pub fn simplify_polygon(points: &[PointF], epsilon: f32) -> Vec<PointF> {

rten-imageproc/src/shapes.rs

@@ -982,10 +982,10 @@ impl<S: AsRef<[Point]>> Polygon<i32, S> {
 
     /// Return true if the pixel with coordinates `p` lies inside the polygon.
     ///
-    /// The intent of this function is to align with [Polygon::fill_iter] such
+    /// The intent of this function is to align with [`Polygon::fill_iter`] such
     /// that `polygon.contains_pixel(p)` is equivalent to
     /// `polygon.fill_iter().any(|fp| fp == p)` but faster because it doesn't
-    /// iterate over every pixel inside the polygon. See [Polygon::fill_iter]
+    /// iterate over every pixel inside the polygon. See [`Polygon::fill_iter`]
     /// for notes on how the inside/outisde status of a pixel is determined.
     pub fn contains_pixel(&self, p: Point) -> bool {
         let mut edge_crossings = 0;
@@ -1126,7 +1126,7 @@ impl Default for Polygons {
     }
 }
 
-/// Iterator over polygons in a [Polygons] collection.
+/// Iterator over polygons in a [`Polygons`] collection.
 pub struct PolygonsIter<'a> {
     points: &'a [Point],
     polygons: Iter<'a, Range<usize>>,

rten-simd/src/dispatch.rs

@@ -76,7 +76,7 @@ impl SimdDispatcher {
 /// Trait for SIMD operations which can be evaluated using different SIMD
 /// vector types.
 ///
-/// To dispatch the operation, create a [SimdDispatcher] and call
+/// To dispatch the operation, create a [`SimdDispatcher`] and call
 /// [`dispatch(op)`](SimdDispatcher::dispatch).
 pub trait SimdOp {
     /// Evaluate the operator using a given SIMD vector type.
@@ -99,7 +99,7 @@ pub trait SimdUnaryOp {
     unsafe fn eval<S: SimdFloat>(&self, x: S) -> S;
 }
 
-/// Apply a vectorized unary function to elements of `input` using [simd_map].
+/// Apply a vectorized unary function to elements of `input` using [`simd_map`].
 pub fn dispatch_map_op<Op: SimdUnaryOp>(input: &[f32], out: &mut [MaybeUninit<f32>], op: Op) {
     let wrapped_op = SimdMapOp::wrap(input.into(), out.into(), op, 0. /* pad */);
     let dispatcher = SimdDispatcher::default();
@@ -115,7 +115,7 @@ pub fn dispatch_map_op_in_place<Op: SimdUnaryOp>(input: &mut [f32], op: Op) {
 }
 
 /// SIMD operation which applies a unary operator `Op` to all elements in
-/// an input buffer using [simd_map].
+/// an input buffer using [`simd_map`].
 pub struct SimdMapOp<Op: SimdUnaryOp> {
     input: PtrLen<f32>,
     output: MutPtrLen<MaybeUninit<f32>>,

rten-tensor/src/copy.rs

@@ -9,7 +9,7 @@ use crate::{
     Matrix, MatrixLayout, MatrixMut, NdTensorView, NdTensorViewMut, TensorView, TensorViewMut,
 };
 
-/// Iterator returned by [range_chunks].
+/// Iterator returned by [`range_chunks`].
 pub struct RangeChunks {
     remainder: Range<usize>,
     chunk_size: usize,
@@ -91,7 +91,7 @@ impl std::iter::FusedIterator for RangeChunksExact {}
 
 /// Return an iterator over sub-ranges of `range`. If `range.len()` is not a
 /// multiple of `chunk_size` then there will be a remainder after iteration
-/// completes, available via [RangeChunksExact::remainder].
+/// completes, available via [`RangeChunksExact::remainder`].
 pub fn range_chunks_exact(range: Range<usize>, chunk_size: usize) -> RangeChunksExact {
     RangeChunksExact {
         remainder: range,

rten-tensor/src/index_iterator.rs

@@ -11,7 +11,7 @@ impl<const N: usize> IndexArray for [usize; N] {}
 pub type DynIndex = SmallVec<[usize; 5]>;
 
 /// Iterator over a range of N-dimensional indices, where N may be known at
-/// compile time (see [NdIndices]) or only at runtime ([DynIndices]).
+/// compile time (see [`NdIndices`]) or only at runtime ([`DynIndices`]).
 ///
 /// The number of dimensions may be zero, in which case the iterator will yield
 /// a single empty index. This is consistent with eg. `ndindex` in NumPy.
@@ -175,7 +175,7 @@ impl<const N: usize> Iterator for NdIndices<N> {
 impl<const N: usize> ExactSizeIterator for NdIndices<N> {}
 impl<const N: usize> FusedIterator for NdIndices<N> {}
 
-/// Max tensor rank supported by the variant of [DynIndices] that is optimized
+/// Max tensor rank supported by the variant of [`DynIndices`] that is optimized
 /// for small-rank tensors.
 const DYN_SMALL_LEN: usize = 4;
 

rten-tensor/src/iterators.rs

@@ -15,7 +15,7 @@ use super::{
 };
 
 /// Borrowed reference to a tensor's data and layout. This differs from
-/// [TensorView] in that it borrows the layout rather than having its own.
+/// [`TensorView`] in that it borrows the layout rather than having its own.
 ///
 /// `'d` is the lifetime of the data and `'l` the lifetime of the layout.
 pub(crate) struct ViewRef<'d, 'l, T, L: Layout> {
@@ -46,7 +46,7 @@ impl<'d, 'l, T, L: Layout> Clone for ViewRef<'d, 'l, T, L> {
 }
 
 /// Mutably borrowed reference to a tensor's data and layout. This differs from
-/// [TensorViewMut] in that it borrows the layout rather than having its own.
+/// [`TensorViewMut`] in that it borrows the layout rather than having its own.
 pub(crate) struct MutViewRef<'d, 'l, T, L: Layout> {
     data: ViewMutData<'d, T>,
     layout: &'l L,
@@ -603,9 +603,9 @@ impl<'a, T> ExactSizeIterator for Lanes<'a, T> {}
 
 impl<'a, T> FusedIterator for Lanes<'a, T> {}
 
-/// Mutable version of [Lanes].
+/// Mutable version of [`Lanes`].
 ///
-/// Unlike [Lanes], this does not implement [Iterator] due to complications
+/// Unlike [`Lanes`], this does not implement [`Iterator`] due to complications
 /// in implementing this for an iterator that returns mutable references, but
 /// it has a similar interface.
 pub struct LanesMut<'a, T> {
@@ -894,7 +894,7 @@ impl<'a, T, L: MutLayout> Iterator for InnerIterDynMut<'a, T, L> {
 
 impl<'a, T, L: MutLayout> ExactSizeIterator for InnerIterDynMut<'a, T, L> {}
 
-/// Iterator over slices of a tensor along an axis. See [TensorView::axis_iter].
+/// Iterator over slices of a tensor along an axis. See [`TensorView::axis_iter`].
 pub struct AxisIter<'a, T, L: MutLayout + RemoveDim> {
     view: TensorBase<ViewData<'a, T>, L>,
     axis: usize,
@@ -926,7 +926,7 @@ impl<'a, T, L: MutLayout + RemoveDim> Iterator for AxisIter<'a, T, L> {
     }
 }
 
-/// Iterator over mutable slices of a tensor along an axis. See [TensorViewMut::axis_iter_mut].
+/// Iterator over mutable slices of a tensor along an axis. See [`TensorViewMut::axis_iter_mut`].
 pub struct AxisIterMut<'a, T, L: MutLayout + RemoveDim> {
     view: TensorBase<ViewMutData<'a, T>, L>,
     axis: usize,
@@ -975,7 +975,7 @@ impl<'a, T, L: MutLayout + RemoveDim> Iterator for AxisIterMut<'a, T, L> {
     }
 }
 
-/// Iterator over slices of a tensor along an axis. See [TensorView::axis_chunks].
+/// Iterator over slices of a tensor along an axis. See [`TensorView::axis_chunks`].
 pub struct AxisChunks<'a, T, L: MutLayout> {
     remainder: Option<TensorBase<ViewData<'a, T>, L>>,
     axis: usize,
@@ -1017,7 +1017,7 @@ impl<'a, T, L: MutLayout> Iterator for AxisChunks<'a, T, L> {
     }
 }
 
-/// Iterator over mutable slices of a tensor along an axis. See [TensorViewMut::axis_chunks_mut].
+/// Iterator over mutable slices of a tensor along an axis. See [`TensorViewMut::axis_chunks_mut`].
 pub struct AxisChunksMut<'a, T, L: MutLayout> {
     remainder: Option<TensorBase<ViewMutData<'a, T>, L>>,
     axis: usize,

rten-tensor/src/layout.rs

@@ -20,8 +20,8 @@ pub fn is_valid_permutation(ndim: usize, permutation: &[usize]) -> bool {
 /// size of each, and the mapping between indices and offsets in the data
 /// storage.
 ///
-/// The main implementations are [NdLayout], where the dimension count is known
-/// statically, and [DynLayout], where the dimension count is only known at
+/// The main implementations are [`NdLayout`], where the dimension count is known
+/// statically, and [`DynLayout`], where the dimension count is only known at
 /// runtime.
 pub trait Layout {
     /// Type used to represent indices.
@@ -866,7 +866,7 @@ impl<const N: usize> From<NdLayout<N>> for DynLayout {
     }
 }
 
-/// MutLayout extends [Layout] with methods for creating, modifying and
+/// MutLayout extends [`Layout`] with methods for creating, modifying and
 /// transforming layouts.
 pub trait MutLayout: Layout + Clone {
     /// Create a new contiguous layout with a given shape.
@@ -1212,10 +1212,10 @@ impl<'a> IntoLayout for &'a [usize] {
     }
 }
 
-/// Trait which extends [MutLayout] with support for changing the number of
+/// Trait which extends [`MutLayout`] with support for changing the number of
 /// dimensions in-place.
 ///
-/// This is only implemented for [DynLayout], since layouts that have a static
+/// This is only implemented for [`DynLayout`], since layouts that have a static
 /// rank cannot change their dimension count at runtime.
 pub trait ResizeLayout: MutLayout {
     /// Insert a size-one axis at the given index in the shape. This will have

rten-tensor/src/lib.rs

@@ -60,7 +60,7 @@ pub trait RandomSource<T> {
 
 /// Storage allocation trait.
 ///
-/// This is used by various methods on [TensorBase] with an `_in` suffix,
+/// This is used by various methods on [`TensorBase`] with an `_in` suffix,
 /// which allow the caller to control the allocation of the data buffer for
 /// the returned owned tensor.
 pub trait Alloc {
@@ -76,7 +76,7 @@ impl<A: Alloc> Alloc for &A {
     }
 }
 
-/// Implementation of [Alloc] which wraps the global allocator.
+/// Implementation of [`Alloc`] which wraps the global allocator.
 pub struct GlobalAlloc {}
 
 impl GlobalAlloc {

rten-tensor/src/slice_range.rs

@@ -88,7 +88,7 @@ where
 ///  - `[SliceItem]` slices
 ///
 /// Ranges can be specified using regular Rust ranges (eg. `start..end`,
-/// `start..`, `..end`, `..`) or a [SliceRange], which extends regular Rust
+/// `start..`, `..end`, `..`) or a [`SliceRange`], which extends regular Rust
 /// ranges with support for steps and specifying endpoints using negative
 /// values, which behaves similarly to using negative values in NumPy.
 pub trait IntoSliceItems {
@@ -157,22 +157,22 @@ impl<T1: Into<SliceItem>, T2: Into<SliceItem>, T3: Into<SliceItem>, T4: Into<Sli
     }
 }
 
-/// Dynamically sized array of [SliceItem]s, which avoids allocating in the
+/// Dynamically sized array of [`SliceItem`]s, which avoids allocating in the
 /// common case where the length is small.
 pub type DynSliceItems = SmallVec<[SliceItem; 5]>;
 
-/// Convert a slice of indices into [SliceItem]s.
+/// Convert a slice of indices into [`SliceItem`]s.
 ///
-/// To convert indices of a statically known length to [SliceItem]s, use
-/// [IntoSliceItems] instead. This function is for the case when the length
+/// To convert indices of a statically known length to [`SliceItem`]s, use
+/// [`IntoSliceItems`] instead. This function is for the case when the length
 /// is not statically known, but is assumed to likely be small.
 pub fn to_slice_items<T: Clone + Into<SliceItem>>(index: &[T]) -> DynSliceItems {
     index.iter().map(|x| x.clone().into()).collect()
 }
 
-/// A range for slicing a [Tensor](crate::Tensor) or [NdTensor](crate::NdTensor).
+/// A range for slicing a [`Tensor`](crate::Tensor) or [`NdTensor`](crate::NdTensor).
 ///
-/// This has two main differences from [Range].
+/// This has two main differences from [`Range`].
 ///
 /// - A non-zero step between indices can be specified. The step can be negative,
 ///   which means that the dimension should be traversed in reverse order.
@@ -468,7 +468,7 @@ impl IntoIterator for IndexRange {
     }
 }
 
-/// An iterator over the indices in an [IndexRange].
+/// An iterator over the indices in an [`IndexRange`].
 #[derive(Clone, Debug, PartialEq)]
 pub struct IndexRangeIter {
     /// Next index. This is in the range [-1, N] where `N` is the size of