From eb2d7998e2115b414f7247cea057f7befe1b7725 Mon Sep 17 00:00:00 2001
From: Anthony Scemama <scemama@irsamc.ups-tlse.fr>
Date: Mon, 26 Feb 2018 10:43:21 +0100
Subject: [PATCH] Documentation

---
 Utils/Coordinate.mli      | 90 +++++++++++++++++++++++++++++++++------
 Utils/Coordinate_type.ml  | 24 -----------
 Utils/Coordinate_type.mli | 11 -----
 Utils/Point.mli           |  3 ++
 4 files changed, 80 insertions(+), 48 deletions(-)
 delete mode 100644 Utils/Coordinate_type.ml
 delete mode 100644 Utils/Coordinate_type.mli

diff --git a/Utils/Coordinate.mli b/Utils/Coordinate.mli
index dee7a71..47ba83f 100644
--- a/Utils/Coordinate.mli
+++ b/Utils/Coordinate.mli
@@ -1,19 +1,83 @@
-type bohr = Bohr.t
-type angstrom = Angstrom.t
+(** Type for coordinates in 3D space.
+
+  All operations on points are done in atomic units. Therefore, 
+  all coordinates are given in {!Bohr.t} and manipulated with this
+  module.
+ *)
+
+type t = Bohr.t
 
-type t = bohr
 type axis = X | Y | Z
 
-val bohr_to_angstrom : bohr -> angstrom 
-val angstrom_to_bohr : angstrom -> bohr
+val bohr_to_angstrom : Bohr.t -> Angstrom.t 
+(** Converts a point in Bohr to Angstrom. *)
 
-val zero : bohr
 
-val ( |. ) : float -> bohr -> bohr
-val ( |+ ) : bohr -> bohr -> bohr
-val ( |- ) : bohr -> bohr -> bohr
-val neg : bohr -> bohr
-val dot : bohr -> bohr -> float
-val norm : bohr -> float
-val get : axis -> bohr -> float
+val angstrom_to_bohr : Angstrom.t -> Bohr.t
+(** Converts a point in Angstrom to Bohr. *)
+
+
+val zero : Bohr.t
+(** [zero = { Bohr.x = 0. ; y=0. ; z=0. }] *)
+
+
+val get : axis -> Bohr.t -> float
+(** Extracts the projection of the coordinate on an axis.
+
+  Example:
+  
+  [Coordinate.(get Y) { Bohr.x=1. ; y=2. ; z=3. } -> 2.]
+
+*)
+
+
+(** {1 Vector operations} *)
+
+
+val ( |. ) : float -> Bohr.t -> Bohr.t
+(** Scale by a float.
+
+  Example:
+
+  [ 2. |. { Bohr.x=1. ; y=2. ; z=3. } -> { Bohr.x=2. ; y=4. ; z=6. } ]
+
+ *)
+
+
+val ( |+ ) : Bohr.t -> Bohr.t -> Bohr.t
+(** Add two vectors.
+
+  Example:
+
+  {[{ Bohr.x=1. ; y=2. ; z=3. } |+ { Bohr.x=2. ; y=3. ; z=1. } ->
+    { Bohr.x=3. ; y=5. ; z=4. }]}
+
+ *)
+
+
+val ( |- ) : Bohr.t -> Bohr.t -> Bohr.t
+(** Subtract two vectors.
+
+  Example:
+
+  {[{ Bohr.x=1. ; y=2. ; z=3. } |- { Bohr.x=2. ; y=3. ; z=1. } ->
+    { Bohr.x=-1. ; y=-1. ; z=2. }]}
+
+ *)
+
+
+val neg : Bohr.t -> Bohr.t
+(** Example:
+
+{[Coordinate.neg { Bohr.x=1. ; y=2. ; z=-3. } ->
+    { Bohr.x=-1. ; y=-2. ; z=3. }]}
+
+ *)
+
+val dot : Bohr.t -> Bohr.t -> float
+(** Dot product. *)
+
+
+val norm : Bohr.t -> float
+(** L{^2} norm of the vector. *)
 
diff --git a/Utils/Coordinate_type.ml b/Utils/Coordinate_type.ml
deleted file mode 100644
index 25f8504..0000000
--- a/Utils/Coordinate_type.ml
+++ /dev/null
@@ -1,24 +0,0 @@
-
-let bohr_to_angstrom { Bohr.x ; y ; z } = 
-  let b_to_a b = Constants.a0 *. b in
-  Angstrom.make 
-  {
-    Point.
-    x = b_to_a x ;
-    y = b_to_a y ;
-    z = b_to_a z ;
-  }
-
-
-
-let angstrom_to_bohr { Angstrom.x ; y ; z } =  
-  let a_to_b a = Constants.a0_inv *. a in
-  Bohr.make 
-  {
-    Point.
-    x = a_to_b x ;
-    y = a_to_b y ;
-    z = a_to_b z ;
-  }
-
-
diff --git a/Utils/Coordinate_type.mli b/Utils/Coordinate_type.mli
deleted file mode 100644
index 5d2cbb2..0000000
--- a/Utils/Coordinate_type.mli
+++ /dev/null
@@ -1,11 +0,0 @@
-(** Coordinate_type can be Bohr or Angstrom. This module provides the conversion
-  functions from {!Bohr.t} to {!Angstrom.t} and from {!Angstrom.t} to {!Bohr.t} *)
-
-type bohr = Bohr.t
-type angstrom = Angstrom.t
-
-val bohr_to_angstrom : bohr -> angstrom 
-val angstrom_to_bohr : angstrom -> bohr
-
-
-
diff --git a/Utils/Point.mli b/Utils/Point.mli
index 78237ef..8ccd5aa 100644
--- a/Utils/Point.mli
+++ b/Utils/Point.mli
@@ -1,3 +1,6 @@
+(** A point in a 3D space. Used by {!Angstrom.t} and {!Bohr.t}.
+ *)
+
 type t = {
   x : float ;
   y : float ;