# HG changeset patch
# User Tuomo Valkonen <tuomov@iki.fi>
# Date 1729604386 18000
# Node ID f67949050a32e7b235d1e974c067ec8ab1e6f388
# Parent  3b05a8b45b953c64045e935f9cf8491a8b3bd8dd
documentation

diff -r 3b05a8b45b95 -r f67949050a32 src/cube.rs
--- a/src/cube.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/cube.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Implementation of the surface of the 3D cube as a [`ManifoldPoint`].
+*/
 
 use serde_repr::*;
 use serde::Serialize;
@@ -5,6 +8,7 @@
 use alg_tools::norms::{Norm, L2};
 use crate::manifold::{ManifoldPoint, EmbeddedManifoldPoint};
 
+/// All the difference faces of a [`OnCube`].
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize_repr, Deserialize_repr)]
 #[repr(u8)]
 pub enum Face {F1 = 1, F2 = 2, F3 = 3, F4 = 4, F5 = 5, F6 = 6}
@@ -180,10 +184,17 @@
         }
     }
 
+    /// Indicates whether an unfolded point `p` is on this face, i.e.,
+    /// has coordinates in [0,1]².
     pub fn is_in_face(&self, p: &Point) -> bool {
         p.iter().map(|t| t.abs()).all(|t| 0.0 <= t && t <= 1.0)
     }
 
+    /// Given an unfolded point `p`, possibly outside this face, finds
+    /// the edge, presented by an adjacent face, in whose direction it is.
+    ///
+    /// **TODO:** this does not correctly handle corners, i.e., when the point is not in
+    /// the direction of an adjacent face.
     pub fn find_crossing(&self, p : &Point) -> Face {
         let &Loc([x, y]) = p;
         use std::cmp::Ordering::*;
@@ -246,6 +257,7 @@
         (best_tan, best_len)
     }
 
+    /// Returns the face of this point.
     pub fn face(&self) -> Face {
         self.face
     }
diff -r 3b05a8b45b95 -r f67949050a32 src/dist.rs
--- a/src/dist.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/dist.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Implementations of the distance function and the distance function squared, on manifolds.
+*/
 
 use alg_tools::mapping::Apply;
 use crate::manifold::ManifoldPoint;
diff -r 3b05a8b45b95 -r f67949050a32 src/fb.rs
--- a/src/fb.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/fb.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Implementation of the forward-backward method on manifolds.
+*/
 
 use alg_tools::iterate::{AlgIteratorFactory, LogRepr};
 use alg_tools::mapping::{Mapping, Sum};
diff -r 3b05a8b45b95 -r f67949050a32 src/main.rs
--- a/src/main.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/main.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Optimisation on non-Riemannian manifolds.
+*/
 
 // We use unicode. We would like to use much more of it than Rust allows.
 // Live with it. Embrace it.
@@ -25,6 +28,7 @@
 mod dist;
 mod zero;
 
+/// Program entry point
 fn main() {
     simple_cube_test().unwrap()
 }
@@ -40,6 +44,7 @@
     z : f64
 }
 
+/// Location for saving results
 static PREFIX : &str = "res";
 
 /// A simple test on the cube
diff -r 3b05a8b45b95 -r f67949050a32 src/manifold.rs
--- a/src/manifold.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/manifold.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Abstract traits for manifolds.
+*/
 
 use alg_tools::euclidean::Euclidean;
 
diff -r 3b05a8b45b95 -r f67949050a32 src/zero.rs
--- a/src/zero.rs	Tue Oct 22 08:27:45 2024 -0500
+++ b/src/zero.rs	Tue Oct 22 08:39:46 2024 -0500
@@ -1,3 +1,6 @@
+/*!
+Implementation of the the constant zero function on a manifold.
+*/
 
 use alg_tools::mapping::Apply;
 use crate::manifold::ManifoldPoint;