docs: Update some links

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<T>(pub T);
 
@@ -43,7 +43,7 @@ impl<T: Coordinates> Coordinates for Chebyshev<T> {
     }
 }
 
-/// Compute the Chebyshev distance between two points.
+/// Compute the [Chebyshev distance] between two points.
 ///
 /// ```math
 /// \begin{aligned}
@@ -51,6 +51,8 @@ impl<T: Coordinates> Coordinates for Chebyshev<T> {
 /// &= \max_i |x_i - y_i|
 /// \end{aligned}
 /// ```
+///
+/// [Chebyshev distance]: https://en.wikipedia.org/wiki/Chebyshev_distance
 pub fn chebyshev_distance<T, U>(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<T: Value> Coordinates for [T] {
     type Value = T;
 
@@ -37,7 +37,7 @@ impl<T: Value> Coordinates for [T] {
     }
 }
 
-/// [Coordinates] implementation for arrays.
+/// [`Coordinates`] implementation for arrays.
 macro_rules! array_coordinates {
     ($n:expr) => (
         impl<T: Value> 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<T: Value> Coordinates for Vec<T> {
     type Value = T;
 
@@ -76,7 +76,7 @@ impl<T: Value> Coordinates for Vec<T> {
     }
 }
 
-/// Blanket [Coordinates] implementation for references.
+/// Blanket [`Coordinates`] implementation for references.
 impl<T: ?Sized + Coordinates> Coordinates for &T {
     type Value = T::Value;
 
@@ -97,7 +97,7 @@ pub trait CoordinateProximity<T> {
     fn distance_to_coords(&self, coords: &[T]) -> Self::Distance;
 }
 
-/// Blanket [CoordinateProximity] implementation for references.
+/// Blanket [`CoordinateProximity`] implementation for references.
 impl<T: CoordinateProximity<U>, U> CoordinateProximity<U> for &T {
     type Distance = T::Distance;
 
@@ -109,5 +109,5 @@ impl<T: CoordinateProximity<U>, U> CoordinateProximity<U> for &T {
 /// Marker trait for coordinate proximities that are [metrics][crate::distance::Metric].
 pub trait CoordinateMetric<T>: CoordinateProximity<T> {}
 
-/// Blanket [CoordinateMetric] implementation for references.
+/// Blanket [`CoordinateMetric`] implementation for references.
 impl<T: CoordinateMetric<U>, U> CoordinateMetric<U> 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<T, U>(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<T>(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<T>(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<T>(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<T>(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<T: Num + NumAssign + Signed + Copy + PartialOrd> 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<T: Value> Distance for T {
     type Value = T;
 }
@@ -72,7 +72,7 @@ pub trait Proximity<T: ?Sized = Self> {
 /// Shorthand for `K::Distance::Value`.
 pub type DistanceValue<K, V = K> = <<K as Proximity<V>>::Distance as Distance>::Value;
 
-/// Blanket [Proximity] implementation for references.
+/// Blanket [`Proximity`] implementation for references.
 impl<'k, 'v, K: Proximity<V>, V> Proximity<&'v V> for &'k K {
     type Distance = K::Distance;
 
@@ -110,5 +110,5 @@ impl<'k, 'v, K: Proximity<V>, V> Proximity<&'v V> for &'k K {
 /// [pseudometric spaces]: https://en.wikipedia.org/wiki/Pseudometric_space
 pub trait Metric<T: ?Sized = Self>: Proximity<T> {}
 
-/// Blanket [Metric] implementation for references.
+/// Blanket [`Metric`] implementation for references.
 impl<'k, 'v, K: Metric<V>, 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<T>(pub T);
 
@@ -46,7 +46,7 @@ impl<T: Coordinates> Coordinates for Euclidean<T> {
     }
 }
 
-/// Compute the Euclidean distance between two points.
+/// Compute the [Euclidean distance] between two points.
 ///
 /// ```math
 /// \begin{aligned}
@@ -54,6 +54,8 @@ impl<T: Coordinates> Coordinates for Euclidean<T> {
 /// &= \sqrt{\sum_i (x_i - y_i)^2}
 /// \end{aligned}
 /// ```
+///
+/// [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance
 pub fn euclidean_distance<T, U>(x: T, y: U) -> EuclideanDistance<T::Value>
 where
     T: Coordinates,
@@ -175,7 +177,7 @@ impl<T: Value> EuclideanDistance<T> {
     }
 }
 
-/// 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<T>(Vec<T>);
 
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<T>(pub T);
 
@@ -24,7 +24,7 @@ impl<T> Hamming<T> {
     }
 }
 
-/// Compute the Hamming distance between two integers.
+/// Compute the [Hamming distance] between two integers.
 ///
 /// ```math
 /// \begin{aligned}
@@ -32,6 +32,8 @@ impl<T> Hamming<T> {
 /// &= \mathrm{popcount}(x \wedge y)
 /// \end{aligned}
 /// ```
+///
+/// [Hamming distance]: https://en.wikipedia.org/wiki/Hamming_distance
 pub fn hamming_distance<T: PrimInt>(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<T: Coordinates> KdNode<T> {
     }
 }
 
-/// 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<V: ?Sized = Self>
 where
     Self: Coordinates<Value = V::Value>,
@@ -90,7 +90,7 @@ where
     V: Coordinates,
 {}
 
-/// Blanket [KdProximity] implementation.
+/// Blanket [`KdProximity`] implementation.
 impl<K, V> KdProximity<V> for K
 where
     K: Coordinates<Value = V::Value>,
@@ -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<V: ?Sized = Self>
 where
     Self: KdProximity<V>,
@@ -108,7 +108,7 @@ where
     V: Coordinates,
 {}
 
-/// Blanket [KdMetric] implementation.
+/// Blanket [`KdMetric`] implementation.
 impl<K, V> KdMetric<V> for K
 where
     K: KdProximity<V>,
@@ -240,7 +240,7 @@ impl<T: Coordinates> KdTree<T> {
 
     /// 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<T>(pub T);
 
@@ -43,7 +43,7 @@ impl<T: Coordinates> Coordinates for Taxicab<T> {
     }
 }
 
-/// Compute the taxicab distance between two points.
+/// Compute the [taxicab distance] between two points.
 ///
 /// ```math
 /// \begin{aligned}
@@ -51,6 +51,8 @@ impl<T: Coordinates> Coordinates for Taxicab<T> {
 /// &= \sum_i |x_i - y_i|
 /// \end{aligned}
 /// ```
+///
+/// [taxicab distance]: https://en.wikipedia.org/wiki/Taxicab_geometry
 pub fn taxicab_distance<T, U>(x: T, y: U) -> T::Value
 where
     T: Coordinates,