From 07e61231dff21fda6da32929c0eae82fa44f6517 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Sat, 27 Jun 2020 17:17:10 -0400 Subject: docs: Update some links --- src/chebyshev.rs | 8 +++++--- src/coords.rs | 12 ++++++------ src/cos.rs | 22 +++++++++++----------- src/distance.rs | 8 ++++---- src/euclid.rs | 10 ++++++---- src/exhaustive.rs | 2 +- src/hamming.rs | 6 ++++-- src/kd.rs | 14 +++++++------- src/lib.rs | 44 +++++++++++++++++++++++--------------------- src/taxi.rs | 10 ++++++---- 10 files changed, 73 insertions(+), 63 deletions(-) diff --git a/src/chebyshev.rs b/src/chebyshev.rs index 335b6f1..bddbd5e 100644 --- a/src/chebyshev.rs +++ b/src/chebyshev.rs @@ -9,8 +9,8 @@ use num_traits::{zero, Signed}; /// /// This wrapper equips any [coordinate space] with the [Chebyshev distance] metric. /// -/// [coordinate space]: [Coordinates] -/// [Chebyshev distance]: https://en.wikipedia.org/wiki/Chebyshev_distance +/// [coordinate space]: Coordinates +/// [Chebyshev distance]: chebyshev_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Chebyshev(pub T); @@ -43,7 +43,7 @@ impl Coordinates for Chebyshev { } } -/// Compute the Chebyshev distance between two points. +/// Compute the [Chebyshev distance] between two points. /// /// ```math /// \begin{aligned} @@ -51,6 +51,8 @@ impl Coordinates for Chebyshev { /// &= \max_i |x_i - y_i| /// \end{aligned} /// ``` +/// +/// [Chebyshev distance]: https://en.wikipedia.org/wiki/Chebyshev_distance pub fn chebyshev_distance(x: T, y: U) -> T::Value where T: Coordinates, diff --git a/src/coords.rs b/src/coords.rs index 08e807c..a95e378 100644 --- a/src/coords.rs +++ b/src/coords.rs @@ -24,7 +24,7 @@ pub trait Coordinates { } } -/// [Coordinates] implementation for slices. +/// [`Coordinates`] implementation for slices. impl Coordinates for [T] { type Value = T; @@ -37,7 +37,7 @@ impl Coordinates for [T] { } } -/// [Coordinates] implementation for arrays. +/// [`Coordinates`] implementation for arrays. macro_rules! array_coordinates { ($n:expr) => ( impl Coordinates for [T; $n] { @@ -63,7 +63,7 @@ array_coordinates!(6); array_coordinates!(7); array_coordinates!(8); -/// [Coordinates] implemention for vectors. +/// [`Coordinates`] implemention for vectors. impl Coordinates for Vec { type Value = T; @@ -76,7 +76,7 @@ impl Coordinates for Vec { } } -/// Blanket [Coordinates] implementation for references. +/// Blanket [`Coordinates`] implementation for references. impl Coordinates for &T { type Value = T::Value; @@ -97,7 +97,7 @@ pub trait CoordinateProximity { fn distance_to_coords(&self, coords: &[T]) -> Self::Distance; } -/// Blanket [CoordinateProximity] implementation for references. +/// Blanket [`CoordinateProximity`] implementation for references. impl, U> CoordinateProximity for &T { type Distance = T::Distance; @@ -109,5 +109,5 @@ impl, U> CoordinateProximity for &T { /// Marker trait for coordinate proximities that are [metrics][crate::distance::Metric]. pub trait CoordinateMetric: CoordinateProximity {} -/// Blanket [CoordinateMetric] implementation for references. +/// Blanket [`CoordinateMetric`] implementation for references. impl, U> CoordinateMetric for &T {} diff --git a/src/cos.rs b/src/cos.rs index 5d8f73f..99a08f4 100644 --- a/src/cos.rs +++ b/src/cos.rs @@ -10,7 +10,7 @@ use std::cmp::Ordering; /// Compute the [cosine *similarity*] between two points. /// -/// Use [cosine_distance] instead if you are implementing [Proximity::distance()]. +/// Use [cosine_distance] instead if you are implementing [`Proximity::distance()`]. /// /// ```math /// \begin{aligned} @@ -21,7 +21,7 @@ use std::cmp::Ordering; /// ``` /// /// [cosine *similarity*]: https://en.wikipedia.org/wiki/Cosine_similarity -/// [Proximity::distance()]: Proximity#tymethod.distance +/// [`Proximity::distance()`]: Proximity#tymethod.distance pub fn cosine_similarity(x: T, y: U) -> T::Value where T: Coordinates, @@ -69,8 +69,8 @@ where /// Equips any [coordinate space] with the [cosine distance] function. /// -/// [coordinate space]: [Coordinates] -/// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity +/// [coordinate space]: Coordinates +/// [cosine distance]: cosine_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Cosine(pub T); @@ -112,7 +112,7 @@ where /// Compute the [cosine *similarity*] between two pre-normalized (unit magnitude) points. /// -/// Use [prenorm_cosine_distance] instead if you are implementing [Proximity::distance()]. +/// Use [`prenorm_cosine_distance()`] instead if you are implementing [`Proximity::distance()`]. /// /// ```math /// \begin{aligned} @@ -166,8 +166,8 @@ where /// Equips any [coordinate space] with the [cosine distance] function for pre-normalized (unit /// magnitude) points. /// -/// [coordinate space]: [Coordinates] -/// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity +/// [coordinate space]: Coordinates +/// [cosine distance]: prenorm_cosine_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct PrenormCosine(pub T); @@ -230,8 +230,8 @@ where /// Equips any [coordinate space] with the [angular distance] metric. /// -/// [coordinate space]: [Coordinates] -/// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity +/// [coordinate space]: Coordinates +/// [angular distance]: angular_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Angular(pub T); @@ -322,8 +322,8 @@ where /// Equips any [coordinate space] with the [angular distance] metric for pre-normalized (unit /// magnitude) points. /// -/// [coordinate space]: [Coordinates] -/// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity +/// [coordinate space]: Coordinates +/// [angular distance]: prenorm_angular_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct PrenormAngular(pub T); diff --git a/src/distance.rs b/src/distance.rs index 20d862b..0fc1c2a 100644 --- a/src/distance.rs +++ b/src/distance.rs @@ -7,7 +7,7 @@ use num_traits::{Num, NumAssign, Signed}; /// This trait is automatically implemented for all types that support the required operations. pub trait Value: Copy + Num + NumAssign + Signed + PartialOrd {} -/// Blanket [Value] implementation. +/// Blanket [`Value`] implementation. impl Value for T {} /// A distance between two points. @@ -44,7 +44,7 @@ where } } -/// Any numerical distance value can be a [Distance]. +/// Any numerical distance value can be a [`Distance`]. impl Distance for T { type Value = T; } @@ -72,7 +72,7 @@ pub trait Proximity { /// Shorthand for `K::Distance::Value`. pub type DistanceValue = <>::Distance as Distance>::Value; -/// Blanket [Proximity] implementation for references. +/// Blanket [`Proximity`] implementation for references. impl<'k, 'v, K: Proximity, V> Proximity<&'v V> for &'k K { type Distance = K::Distance; @@ -110,5 +110,5 @@ impl<'k, 'v, K: Proximity, V> Proximity<&'v V> for &'k K { /// [pseudometric spaces]: https://en.wikipedia.org/wiki/Pseudometric_space pub trait Metric: Proximity {} -/// Blanket [Metric] implementation for references. +/// Blanket [`Metric`] implementation for references. impl<'k, 'v, K: Metric, V> Metric<&'v V> for &'k K {} diff --git a/src/euclid.rs b/src/euclid.rs index 0f2281e..c1d88ae 100644 --- a/src/euclid.rs +++ b/src/euclid.rs @@ -12,8 +12,8 @@ use std::convert::TryFrom; /// /// This wrapper equips any [coordinate space] with the [Euclidean distance] metric. /// -/// [coordinate space]: [Coordinates] -/// [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance +/// [coordinate space]: Coordinates +/// [Euclidean distance]: euclidean_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Euclidean(pub T); @@ -46,7 +46,7 @@ impl Coordinates for Euclidean { } } -/// Compute the Euclidean distance between two points. +/// Compute the [Euclidean distance] between two points. /// /// ```math /// \begin{aligned} @@ -54,6 +54,8 @@ impl Coordinates for Euclidean { /// &= \sqrt{\sum_i (x_i - y_i)^2} /// \end{aligned} /// ``` +/// +/// [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance pub fn euclidean_distance(x: T, y: U) -> EuclideanDistance where T: Coordinates, @@ -175,7 +177,7 @@ impl EuclideanDistance { } } -/// Error type for failed conversions from negative numbers to [EuclideanDistance]. +/// Error type for failed conversions from negative numbers to [`EuclideanDistance`]. #[derive(Debug)] pub struct NegativeDistanceError; diff --git a/src/exhaustive.rs b/src/exhaustive.rs index 909edda..221641c 100644 --- a/src/exhaustive.rs +++ b/src/exhaustive.rs @@ -5,7 +5,7 @@ use crate::{ExactNeighbors, NearestNeighbors, Neighborhood}; use std::iter::FromIterator; -/// A [NearestNeighbors] implementation that does exhaustive search. +/// A [`NearestNeighbors`] implementation that does exhaustive search. #[derive(Debug)] pub struct ExhaustiveSearch(Vec); diff --git a/src/hamming.rs b/src/hamming.rs index da959b4..b3a7e78 100644 --- a/src/hamming.rs +++ b/src/hamming.rs @@ -8,7 +8,7 @@ use num_traits::PrimInt; /// /// This wrapper equips any integer with the [Hamming distance] metric. /// -/// [Hamming distance]: https://en.wikipedia.org/wiki/Hamming_distance +/// [Hamming distance]: hamming_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Hamming(pub T); @@ -24,7 +24,7 @@ impl Hamming { } } -/// Compute the Hamming distance between two integers. +/// Compute the [Hamming distance] between two integers. /// /// ```math /// \begin{aligned} @@ -32,6 +32,8 @@ impl Hamming { /// &= \mathrm{popcount}(x \wedge y) /// \end{aligned} /// ``` +/// +/// [Hamming distance]: https://en.wikipedia.org/wiki/Hamming_distance pub fn hamming_distance(x: T, y: T) -> i32 { (x ^ y).count_ones() as i32 } diff --git a/src/kd.rs b/src/kd.rs index 69c72bf..2a9ecb4 100644 --- a/src/kd.rs +++ b/src/kd.rs @@ -81,7 +81,7 @@ impl KdNode { } } -/// Marker trait for [Proximity] implementations that are compatible with k-d trees. +/// Marker trait for [`Proximity`] implementations that are compatible with k-d trees. pub trait KdProximity where Self: Coordinates, @@ -90,7 +90,7 @@ where V: Coordinates, {} -/// Blanket [KdProximity] implementation. +/// Blanket [`KdProximity`] implementation. impl KdProximity for K where K: Coordinates, @@ -99,7 +99,7 @@ where V: Coordinates, {} -/// Marker trait for [Metric] implementations that are compatible with k-d tree. +/// Marker trait for [`Metric`] implementations that are compatible with k-d tree. pub trait KdMetric where Self: KdProximity, @@ -108,7 +108,7 @@ where V: Coordinates, {} -/// Blanket [KdMetric] implementation. +/// Blanket [`KdMetric`] implementation. impl KdMetric for K where K: KdProximity, @@ -240,7 +240,7 @@ impl KdTree { /// Push a new item into the tree. /// - /// Inserting elements individually tends to unbalance the tree. Use [KdTree::balanced] if + /// Inserting elements individually tends to unbalance the tree. Use [`KdTree::balanced()`] if /// possible to create a balanced tree from a batch of items. pub fn push(&mut self, item: T) { if let Some(root) = &mut self.root { @@ -413,8 +413,8 @@ where /// A [k-d tree] stored as a flat array. /// -/// A FlatKdTree is always balanced and usually more efficient than a [KdTree], but doesn't support -/// dynamic updates. +/// A FlatKdTree is always balanced and usually more efficient than a [`KdTree`], but doesn't +/// support dynamic updates. /// /// [k-d tree]: https://en.wikipedia.org/wiki/K-d_tree #[derive(Debug)] diff --git a/src/lib.rs b/src/lib.rs index e6ca957..346e9e9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,18 +2,19 @@ //! //! # Overview //! -//! The notion of distances between points is captured by the [Proximity] trait. Its [`distance()`] -//! method returns a [Distance], from which the actual numerical distance may be retrieved with -//! [`value()`]. These layers of abstraction allow `acap` to work with generically with different -//! distance functions over different types. +//! The notion of distances between points is captured by the [`Proximity`] trait. Its +//! [`distance()`] method returns a [`Distance`], from which the actual numerical distance may be +//! retrieved with [`value()`]. These layers of abstraction allow `acap` to work with generically +//! with different distance functions over different types. //! -//! There are no restrictions on the distances computed by a [Proximity]. For example, they don't +//! There are no restrictions on the distances computed by a [`Proximity`]. For example, they don't //! have to be symmetric, subadditive, or even positive. Implementations that do have these -//! desirable properties will additionally implement the [Metric] marker trait. This distinction +//! desirable properties will additionally implement the [`Metric`] marker trait. This distinction //! allows `acap` to support a wide variety of useful metric and non-metric distances. //! -//! As a concrete example, consider `Euclidean<[i32; 2]>`. The [Euclidean] wrapper equips any type -//! that has [coordinates] with the [Euclidean distance] function as its Proximity implementation: +//! As a concrete example, consider `Euclidean<[i32; 2]>`. The [`Euclidean`] wrapper equips any +//! type that has [coordinates] with the [Euclidean distance] function as its [`Proximity`] +//! implementation: //! //! use acap::distance::Proximity; //! use acap::euclid::Euclidean; @@ -23,7 +24,7 @@ //! assert_eq!(a.distance(&b), 5); //! //! In this case, `distance()` doesn't return a number directly; as an optimization, it returns a -//! [EuclideanDistance] wrapper. This wrapper stores the squared value of the distance, to avoid +//! [`EuclideanDistance`] wrapper. This wrapper stores the squared value of the distance, to avoid //! computing square roots until absolutely necessary. Still, it transparently supports comparisons //! with numerical values: //! @@ -38,9 +39,10 @@ //! assert_eq!(d, 5); //! assert_eq!(d.value(), 5.0f32); //! -//! For finding the nearest neighbors to a point from a set of other points, the [NearestNeighbors] -//! trait provides a uniform interface to [many different similarity search data structures]. One -//! such structure is the [vantage-point tree], available in `acap` as [VpTree]: +//! For finding the nearest neighbors to a point from a set of other points, the +//! [`NearestNeighbors`] trait provides a uniform interface to [many different similarity search +//! data structures]. One such structure is the [vantage-point tree], available in `acap` as +//! [`VpTree`]: //! //! # use acap::euclid::Euclidean; //! use acap::vp::VpTree; @@ -53,9 +55,9 @@ //! Euclidean([7, 24]), //! ]); //! -//! [VpTree] implements [NearestNeighbors], which has a [`nearest()`] method that returns an -//! optional [Neighbor]. The [Neighbor] struct holds the actual neighbor it found, and the distance -//! it was from the target: +//! [`VpTree`] implements [`NearestNeighbors`], which has a [`nearest()`] method that returns an +//! optional [`Neighbor`]. The [`Neighbor`] struct holds the actual neighbor it found, and the +//! distance it was from the target: //! //! # use acap::euclid::Euclidean; //! # use acap::vp::VpTree; @@ -67,15 +69,15 @@ //! assert_eq!(nearest.item, &Euclidean([3, 4])); //! assert_eq!(nearest.distance, 5); //! -//! [NearestNeighbors] also provides the [`nearest_within()`], [`k_nearest()`], and +//! [`NearestNeighbors`] also provides the [`nearest_within()`], [`k_nearest()`], and //! [`k_nearest_within()`] methods which find up to `k` neighbors within a possible threshold. //! //! It can be expensive to compute nearest neighbors exactly, especially in high dimensions. -//! For performance reasons, [NearestNeighbors] implementations are allowed to return approximate +//! For performance reasons, [`NearestNeighbors`] implementations are allowed to return approximate //! results. Many implementations have a speed/accuracy tradeoff which can be tuned. Those -//! implementations which always return exact results will also implement the [ExactNeighbors] -//! marker trait. For example, a [VpTree] will be exact when the [Proximity] function is a -//! [Metric]. +//! implementations which always return exact results will also implement the [`ExactNeighbors`] +//! marker trait. For example, a [`VpTree`] will be exact when the [`Proximity`] function is a +//! [`Metric`]. //! //! [nearest neighbor search]: https://en.wikipedia.org/wiki/Nearest_neighbor_search //! [`distance()`]: Proximity#tymethod.distance @@ -84,7 +86,7 @@ //! [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance //! [many different similarity search data structures]: NearestNeighbors#implementors //! [vantage-point tree]: https://en.wikipedia.org/wiki/Vantage-point_tree -//! [VpTree]: vp::VpTree +//! [`VpTree`]: vp::VpTree //! [`nearest()`]: NearestNeighbors#method.nearest //! [`k_nearest()`]: NearestNeighbors#method.k_nearest //! [`nearest_within()`]: NearestNeighbors#method.nearest_within diff --git a/src/taxi.rs b/src/taxi.rs index f22afb0..8bbe2f3 100644 --- a/src/taxi.rs +++ b/src/taxi.rs @@ -7,10 +7,10 @@ use num_traits::{zero, Signed}; /// A point in taxicab space. /// -/// This wrapper equips any [coordinate space] with the [taxicab distance metric]. +/// This wrapper equips any [coordinate space] with the [taxicab distance] metric. /// -/// [coordinate space]: [Coordinates] -/// [taxicab distance metric]: https://en.wikipedia.org/wiki/Taxicab_geometry +/// [coordinate space]: Coordinates +/// [taxicab distance]: taxicab_distance #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct Taxicab(pub T); @@ -43,7 +43,7 @@ impl Coordinates for Taxicab { } } -/// Compute the taxicab distance between two points. +/// Compute the [taxicab distance] between two points. /// /// ```math /// \begin{aligned} @@ -51,6 +51,8 @@ impl Coordinates for Taxicab { /// &= \sum_i |x_i - y_i| /// \end{aligned} /// ``` +/// +/// [taxicab distance]: https://en.wikipedia.org/wiki/Taxicab_geometry pub fn taxicab_distance(x: T, y: U) -> T::Value where T: Coordinates, -- cgit v1.2.3