From e466113d70e9786259b3516b5951771b0706e5d8 Mon Sep 17 00:00:00 2001
From: Tavian Barnes <tavianator@tavianator.com>
Date: Fri, 26 Jun 2020 17:20:22 -0400
Subject: docs: Integrate KaTeX and add some formulas

---
 src/cos.rs | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

(limited to 'src/cos.rs')

diff --git a/src/cos.rs b/src/cos.rs
index 3d3219c..5d8f73f 100644
--- a/src/cos.rs
+++ b/src/cos.rs
@@ -12,8 +12,16 @@ use std::cmp::Ordering;
 ///
 /// Use [cosine_distance] instead if you are implementing [Proximity::distance()].
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{cosine\_similarity}(x, y) &= \frac{x \cdot y}{\|x\| \|y\|} \\
+/// &= \frac{\sum_i x_i y_i}{\sqrt{\sum_i x_i^2} \sqrt{\sum_i y_i^2}} \\
+/// &= \cos \theta
+/// \end{aligned}
+/// ```
+///
 /// [cosine *similarity*]: https://en.wikipedia.org/wiki/Cosine_similarity
-/// [Proximity::distance()]: Proximity#method.distance
+/// [Proximity::distance()]: Proximity#tymethod.distance
 pub fn cosine_similarity<T, U>(x: T, y: U) -> T::Value
 where
     T: Coordinates,
@@ -39,6 +47,15 @@ where
 
 /// Compute the [cosine distance] between two points.
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{cosine\_distance}(x, y) &= 1 - \mathrm{cosine\_similarity}(x, y) \\
+/// &= 1 - \frac{x \cdot y}{\|x\| \|y\|} \\
+/// &= 1 - \frac{\sum_i x_i y_i}{\sqrt{\sum_i x_i^2} \sqrt{\sum_i y_i^2}} \\
+/// &= 1 - \cos \theta
+/// \end{aligned}
+/// ```
+///
 /// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity
 pub fn cosine_distance<T, U>(x: T, y: U) -> T::Value
 where
@@ -97,8 +114,16 @@ where
 ///
 /// Use [prenorm_cosine_distance] instead if you are implementing [Proximity::distance()].
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{prenorm\_cosine\_similarity}(x, y) &= x \cdot y \\
+/// &= \sum_i x_i y_i \\
+/// &= \cos \theta
+/// \end{aligned}
+/// ```
+///
 /// [cosine *similarity*]: https://en.wikipedia.org/wiki/Cosine_similarity
-/// [`Proximity::distance()`]: Proximity#method.distance
+/// [`Proximity::distance()`]: Proximity#tymethod.distance
 pub fn prenorm_cosine_similarity<T, U>(x: T, y: U) -> T::Value
 where
     T: Coordinates,
@@ -118,6 +143,15 @@ where
 
 /// Compute the [cosine distance] between two pre-normalized (unit magnitude) points.
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{prenorm\_cosine\_distance}(x, y) &= 1 - \mathrm{prenorm\_cosine\_similarity}(x, y) \\
+/// &= 1 - x \cdot y \\
+/// &= 1 - \sum_i x_i y_i \\
+/// &= 1 - \cos \theta
+/// \end{aligned}
+/// ```
+///
 /// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity
 pub fn prenorm_cosine_distance<T, U>(x: T, y: U) -> T::Value
 where
@@ -175,6 +209,15 @@ where
 
 /// Compute the [angular distance] between two points.
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{angular\_distance}(x, y) &= \arccos(\mathrm{cosine\_similarity}(x, y)) \\
+/// &= \arccos \left( \frac{x \cdot y}{\|x\| \|y\|} \right) \\
+/// &= \arccos \left( \frac{\sum_i x_i y_i}{\sqrt{\sum_i x_i^2} \sqrt{\sum_i y_i^2}} \right) \\
+/// &= \theta
+/// \end{aligned}
+/// ```
+///
 /// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity
 pub fn angular_distance<T, U>(x: T, y: U) -> AngularDistance<T::Value>
 where
@@ -257,6 +300,15 @@ where
 
 /// Compute the [angular distance] between two points.
 ///
+/// ```math
+/// \begin{aligned}
+/// \mathrm{prenorm\_angular\_distance}(x, y) &= \arccos(\mathrm{prenorm\_cosine\_similarity}(x, y)) \\
+/// &= \arccos(x \cdot y) \\
+/// &= \arccos \left( \sum_i x_i y_i \right) \\
+/// &= \theta
+/// \end{aligned}
+/// ```
+///
 /// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity
 pub fn prenorm_angular_distance<T, U>(x: T, y: U) -> AngularDistance<T::Value>
 where
-- 
cgit v1.2.3