diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 44 |
1 files changed, 23 insertions, 21 deletions
@@ -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 |