From 3c9b71fa5655d85fed7578263a5cc39bca222089 Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Mon, 8 Apr 2019 14:05:20 +1000
Subject: [PATCH] geom/aabb: add some more documentation

---
 geom/aabb.hpp | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/geom/aabb.hpp b/geom/aabb.hpp
index 08215049..0bbc9ad1 100644
--- a/geom/aabb.hpp
+++ b/geom/aabb.hpp
@@ -40,7 +40,7 @@ namespace cruft::geom {
         }
 
 
-        //---------------------------------------------------------------------
+        ///--------------------------------------------------------------------
         T
         diameter (void) const
         {
@@ -48,14 +48,15 @@ namespace cruft::geom {
         }
 
 
-        //---------------------------------------------------------------------
+        ///--------------------------------------------------------------------
         /// tests whether a point lies within the region, inclusive of borders
         constexpr bool
         inclusive (point<S,T> p) const noexcept
         { return all (lo <= p && hi >= p); }
 
 
-        //---------------------------------------------------------------------
+        ///--------------------------------------------------------------------
+        /// Find's the closest point on the AABB border to the supplied point.
         point<S,T>
         closest (point<S,T> query) const
         {
@@ -63,7 +64,8 @@ namespace cruft::geom {
         }
 
 
-        //---------------------------------------------------------------------
+        ///--------------------------------------------------------------------
+        /// Modifies the AABB to cover the supplied point inclusively.
         void cover (point<S,T> p)
         {
             lo = min (p, lo);
@@ -71,20 +73,24 @@ namespace cruft::geom {
         }
 
 
-        //---------------------------------------------------------------------
+        ///////////////////////////////////////////////////////////////////////
+        /// Adds a constant vector to both the lo and hi points.
         aabb<S,T> operator+ (vector<S,T> v) const
         {
             return { lo + v, hi + v };
         }
 
 
+        ///--------------------------------------------------------------------
+        /// Substracts a constant vector from both the lo and hi points.
         aabb<S,T> operator- (vector<S,T> v) const
         {
             return { lo - v, hi - v };
         }
 
 
-        /// returns an aabb that covers the supplied point in addition to the
+        ///////////////////////////////////////////////////////////////////////
+        /// Returns an aabb that covers the supplied point in addition to the
         /// current aabb area.
         auto operator| [[nodiscard]] (point<S,T> p) const noexcept
         {
@@ -95,11 +101,16 @@ namespace cruft::geom {
         }
 
 
+        ///--------------------------------------------------------------------
+        /// Modifies the AABB to cover the supplied point inclusively.
         auto& operator|= (point<S,T> p) noexcept
         {
             return *this = *this | p;
         }
 
+
+        ///--------------------------------------------------------------------
+        /// Returns an AABB that covers this AABB and the supplied AABB.
         aabb operator| [[nodiscard]] (aabb<S,T> rhs) const noexcept
         {
             return {
@@ -108,11 +119,18 @@ namespace cruft::geom {
             };
         }
 
+
+        ///--------------------------------------------------------------------
+        /// Returns a read only list of vertices for the AABB.
         std::array<cruft::point<S,T>,cruft::pow(2,S)>
         vertices (void) const noexcept;
 
 
+        ///////////////////////////////////////////////////////////////////////
+        /// The most negative corner of the AABB.
         ::cruft::point<S,T> lo;
+
+        /// The most positive corner of the AABB.
         ::cruft::point<S,T> hi;
     };