From 83ddde4f87ee3642ce1f5de43e9e57c3be6e87a9 Mon Sep 17 00:00:00 2001
From: Tavian Barnes
Date: Mon, 29 Jun 2020 16:23:11 -0400
Subject: distance: Expand the Distance docs
---
src/distance.rs | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/src/distance.rs b/src/distance.rs
index 070bac7..e44ed03 100644
--- a/src/distance.rs
+++ b/src/distance.rs
@@ -14,8 +14,8 @@ impl Value for T {}
///
/// An implementation may be an actual numerical distance, or an [order embedding] of the true
/// distance. This allows for optimizations whenever distances can be compared more efficiently
-/// than their exact values can be computed, as is the case for [Euclidean distance]. Implementors
-/// must satisfy, for all distances `$x$` and `$y$`:
+/// than their exact values can be computed. Implementors must satisfy, for all distances `$x$` and
+/// `$y$`:
///
/// ```math
/// \begin{aligned}
@@ -25,8 +25,14 @@ impl Value for T {}
/// \end{aligned}
/// ```
///
+/// Any monotonically increasing function can be used to create an order embedding. For example,
+/// [`EuclideanDistance`] holds a squared distance, rather than the distance itself. Comparisons
+/// still behave correctly because `$x \mapsto x^2$` is an increasing function. This lets us avoid
+/// computing relatively expensive square roots until we need the `value()` itself, at which point
+/// the inverse function `$x \mapsto \sqrt{x}$` must be applied.
+///
/// [order embedding]: https://en.wikipedia.org/wiki/Order_embedding
-/// [Euclidean distance]: crate::euclid::EuclideanDistance
+/// [`EuclideanDistance`]: crate::euclid::EuclideanDistance
pub trait Distance
where
Self: Copy,
--
cgit v1.2.3