From adb812a194961d542dcb0abd61258cbc8723ecd9 Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Sun, 19 May 2013 22:14:39 +0300
Subject: [PATCH] Add basic description for all classes

---
 source/geometry/box.h              | 5 +++++
 source/geometry/circle.h           | 5 +++++
 source/geometry/hyperbox.h         | 4 ++++
 source/geometry/hypersphere.h      | 4 ++++
 source/geometry/rectangle.h        | 5 +++++
 source/geometry/shape.h            | 5 +++++
 source/geometry/surfacepoint.h     | 3 +++
 source/geometry/transformedshape.h | 3 +++
 source/linal/matrix.h              | 2 +-
 source/linal/squarematrix.h        | 4 ++++
 10 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/source/geometry/box.h b/source/geometry/box.h
index 40f88dc..b46eb67 100644
--- a/source/geometry/box.h
+++ b/source/geometry/box.h
@@ -6,6 +6,11 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+The three-dimensional special case of a HyperBox.  This class exists for
+convenience only and does not provide any extra functionality over the base
+class.
+*/
 template<typename T>
 class Box: public HyperBox<T, 3>
 {
diff --git a/source/geometry/circle.h b/source/geometry/circle.h
index ebc1c41..3a2cfc2 100644
--- a/source/geometry/circle.h
+++ b/source/geometry/circle.h
@@ -6,6 +6,11 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+The two-dimensional special case of a HyperSphere.  This class exists for
+convenience only and does not provide any extra functionality over the base
+class.
+*/
 template<typename T>
 class Circle: public HyperSphere<T, 2>
 {
diff --git a/source/geometry/hyperbox.h b/source/geometry/hyperbox.h
index 6248d6b..7d363f2 100644
--- a/source/geometry/hyperbox.h
+++ b/source/geometry/hyperbox.h
@@ -11,6 +11,10 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+A shape bounded by planar faces at right angles to each other.  Two- and three-
+dimensional cases are Rectangle and Box, respectively.
+*/
 template<typename T, unsigned D>
 class HyperBox: public Shape<T, D>
 {
diff --git a/source/geometry/hypersphere.h b/source/geometry/hypersphere.h
index f95ebe4..ed2b49f 100644
--- a/source/geometry/hypersphere.h
+++ b/source/geometry/hypersphere.h
@@ -10,6 +10,10 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+A shape consisting of the points within a specific distance from the origin.
+Two- and three-dimensional cases are Circle and Sphere, respectively.
+*/
 template<typename T, unsigned D>
 class HyperSphere: public Shape<T, D>
 {
diff --git a/source/geometry/rectangle.h b/source/geometry/rectangle.h
index dbebf8a..cbf625c 100644
--- a/source/geometry/rectangle.h
+++ b/source/geometry/rectangle.h
@@ -6,6 +6,11 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+The two-dimensional special case of a HyperBox.  This class exists for
+convenience only and does not provide any extra functionality over the base
+class.
+*/
 template<typename T>
 class Rectangle: public HyperBox<T, 2>
 {
diff --git a/source/geometry/shape.h b/source/geometry/shape.h
index 1f81764..3f52613 100644
--- a/source/geometry/shape.h
+++ b/source/geometry/shape.h
@@ -16,6 +16,11 @@ class Ray;
 template<typename T, unsigned D>
 class SurfacePoint;
 
+/**
+Base class and interface for geometric shapes.  Shapes may be bounded or
+unbounded.  They are always considered to be solid, i.e. have a distinct inside
+and an outside.
+*/
 template<typename T, unsigned D>
 class Shape
 {
diff --git a/source/geometry/surfacepoint.h b/source/geometry/surfacepoint.h
index 3513ac8..251964c 100644
--- a/source/geometry/surfacepoint.h
+++ b/source/geometry/surfacepoint.h
@@ -6,6 +6,9 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+A point on the surface of a shape.
+*/
 template<typename T, unsigned N>
 struct SurfacePoint
 {
diff --git a/source/geometry/transformedshape.h b/source/geometry/transformedshape.h
index ea7281f..0125368 100644
--- a/source/geometry/transformedshape.h
+++ b/source/geometry/transformedshape.h
@@ -8,6 +8,9 @@
 namespace Msp {
 namespace Geometry {
 
+/**
+A shape modified by an affine transformation.
+*/
 template<typename T, unsigned D>
 class TransformedShape: public Shape<T, D>
 {
diff --git a/source/linal/matrix.h b/source/linal/matrix.h
index 6c04454..599c1dc 100644
--- a/source/linal/matrix.h
+++ b/source/linal/matrix.h
@@ -8,7 +8,7 @@ namespace Msp {
 namespace LinAl {
 
 /**
-A general mathematical matrix.
+A general mathematical matrix with M rows and N columns.
 */
 template<typename T, unsigned M, unsigned N>
 class Matrix
diff --git a/source/linal/squarematrix.h b/source/linal/squarematrix.h
index ee86e13..0af9a74 100644
--- a/source/linal/squarematrix.h
+++ b/source/linal/squarematrix.h
@@ -14,6 +14,10 @@ public:
 	virtual ~not_invertible() throw() { }
 };
 
+/**
+A mathematical matrix with S rows and columns.  Some operations are provided
+here that are only possible for square matrices.
+*/
 template<typename T, unsigned S>
 class SquareMatrix: public Matrix<T, S, S>
 {
-- 
2.43.0