Add some comments.

6 files changed, 79 insertions, 12 deletions

diff --git a/libdimensionxx/dimensionxx/canvas.hpp b/libdimensionxx/dimensionxx/canvas.hpp
index c501413..eda9ad3 100644
--- a/libdimensionxx/dimensionxx/canvas.hpp
+++ b/libdimensionxx/dimensionxx/canvas.hpp
@@ -21,29 +21,39 @@
 #ifndef DIMENSIONXX_CANVAS_HPP
 #define DIMENSIONXX_CANVAS_HPP
 
+// dmnsn_canvas* wrapper.
+
 namespace Dimension
 {
+  // Base canvas class.  Wraps a dmnsn_canvas*.
   class Canvas
   {
   public:
-    Canvas(unsigned int width, unsigned int height)
-      : m_canvas(dmnsn_new_canvas(width, height)) { }
+    // Allocate a dmnsn_canvas specified width and height.
+    Canvas(unsigned int width, unsigned int height);
+
+    // Wrap an existing canvas.
     explicit Canvas(dmnsn_canvas* canvas) : m_canvas(canvas) { }
+
+    // Delete the canvas.  (dmnsn_delete_canvas(m_canvas).)
     virtual ~Canvas();
 
-    unsigned int width()  const { return m_canvas->x; }
-    unsigned int height() const { return m_canvas->y; }
+    // Get the width and height.
+    unsigned int width() const;
+    unsigned int height() const;
 
-    Color pixel(unsigned int x, unsigned int y) const
-      { return Color(dmnsn_get_pixel(m_canvas, x, y)); }
-    void pixel(unsigned int x, unsigned int y, const Color& c)
-      { dmnsn_set_pixel(m_canvas, x, y, c.dmnsn()); }
+    // Get and set a pixel, thread-safely.
+    Color pixel(unsigned int x, unsigned int y) const;
+    void pixel(unsigned int x, unsigned int y, const Color& c);
 
-    dmnsn_canvas*       dmnsn()       { return m_canvas; }
-    const dmnsn_canvas* dmnsn() const { return m_canvas; }
+    // Access the wrapped C object.
+    dmnsn_canvas*       dmnsn();
+    const dmnsn_canvas* dmnsn() const;
 
   protected:
-    Canvas() : m_canvas(0) { }
+    // Derived classes may want to set m_canvas later.  Set it to NULL now, so
+    // that the destructor can still dmnsn_delete_canvas it.
+    Canvas();
 
     dmnsn_canvas* m_canvas;
 
diff --git a/libdimensionxx/dimensionxx/color.hpp b/libdimensionxx/dimensionxx/color.hpp
index afd7ea5..a7087a7 100644
--- a/libdimensionxx/dimensionxx/color.hpp
+++ b/libdimensionxx/dimensionxx/color.hpp
@@ -21,16 +21,21 @@
 #ifndef DIMENSIONXX_COLOR_HPP
 #define DIMENSIONXX_COLOR_HPP
 
+// Wrappers for libdimension colors.
+
 namespace Dimension
 {
+  // Forward declarations
   class CIE_XYZ;
   class CIE_xyY;
   class CIE_Lab;
   class CIE_Luv;
   class sRGB;
 
+  // Default whitepoint (D50)
   extern const CIE_XYZ whitepoint;
 
+  // Wrapper for dmnsn_color
   class Color
   {
   public:
@@ -44,6 +49,7 @@ namespace Dimension
     // Color(const Color& c);
     // ~Color();
 
+    // Get and set filtered and unfiltered transparancy
     double filter() const { return m_color.filter; }
     double trans()  const { return m_color.trans; }
 
@@ -51,15 +57,20 @@ namespace Dimension
     double trans(double t)  { m_color.trans = t; }
 
     // Color& operator=(const Color& c);
+
+    // Add a color to this one in a perceptually correct manner
     Color& operator+=(const Color& c)
       { m_color = dmnsn_color_add(m_color, c.m_color); return *this; }
 
+    // Access the wrapped color
     dmnsn_color dmnsn() const { return m_color; }
 
   private:
     dmnsn_color m_color;
   };
 
+  // Wrappers for all libdimension color types
+
   class CIE_XYZ
   {
   public:
@@ -206,6 +217,7 @@ namespace Dimension
 
   // Color operators
 
+  // Perceptually correct color combination
   inline Color
   operator+(const Color& lhs, const Color& rhs)
   {
@@ -214,6 +226,7 @@ namespace Dimension
     return temp;
   }
 
+  // Perceptual color difference
   inline double
   operator-(const Color& lhs, const Color& rhs)
   {
diff --git a/libdimensionxx/dimensionxx/cookie.hpp b/libdimensionxx/dimensionxx/cookie.hpp
index acb783d..639fbfe 100644
--- a/libdimensionxx/dimensionxx/cookie.hpp
+++ b/libdimensionxx/dimensionxx/cookie.hpp
@@ -21,6 +21,9 @@
 #ifndef DIMENSIONXX_COOKIE_HPP
 #define DIMENSIONXX_COOKIE_HPP
 
+// Some internal magic to use C FILE* I/O with C++ streams.  Currently this ties
+// us to Linux and glibc, but in the future, this will be portable.
+
 #include <istream>
 #include <ostream>
 #include <cstdio>
diff --git a/libdimensionxx/dimensionxx/error.hpp b/libdimensionxx/dimensionxx/error.hpp
index 8919895..99670cb 100644
--- a/libdimensionxx/dimensionxx/error.hpp
+++ b/libdimensionxx/dimensionxx/error.hpp
@@ -21,21 +21,29 @@
 #ifndef DIMENSIONXX_ERROR_HPP
 #define DIMENSIONXX_ERROR_HPP
 
+// Wrappers for libdimension error handling, and an exception class.
+// dmnsn_error is still used by libdimensionxx whenever an exception shouldn't
+// be thrown, like in destructors, and whenever libdimension or libdimension-*
+// use it internally.  Exceptions are thrown otherwise to report errors.
+
 #include <dimension.h>
 #include <stdexcept>
 #include <string>
 
 namespace Dimension
 {
+  // Wrapper for dmnsn_severity
   enum Severity {
     SEVERITY_LOW    = DMNSN_SEVERITY_LOW,
     SEVERITY_MEDIUM = DMNSN_SEVERITY_MEDIUM,
     SEVERITY_HIGH   = DMNSN_SEVERITY_HIGH
   };
 
+  // Get or set the resilience, thread-safely
   Severity resilience();
   void resilience(Severity resilience);
 
+  // Generic exception class, derives from std::runtime_error
   class Dimension_Error : public std::runtime_error
   {
   public:
diff --git a/libdimensionxx/dimensionxx/geometry.hpp b/libdimensionxx/dimensionxx/geometry.hpp
index 4295c05..78b9b49 100644
--- a/libdimensionxx/dimensionxx/geometry.hpp
+++ b/libdimensionxx/dimensionxx/geometry.hpp
@@ -21,12 +21,15 @@
 #ifndef DIMENSIONXX_GEOMETRY_HPP
 #define DIMENSIONXX_GEOMETRY_HPP
 
+// Wrappers for geometric types (Scalars, Vectors, Lines (rays)).
+
 #include <dimension.h>
 
 namespace Dimension
 {
-  typedef dmnsn_scalar Scalar;
+  typedef dmnsn_scalar Scalar; // This is really `double'
 
+  // Wrapper for dmnsn_vector
   class Vector
   {
   public:
@@ -37,10 +40,13 @@ namespace Dimension
     // Vector(const Vector& v);
     // ~Vector();
 
+    // Get the x, y, and z components.
     Scalar x() const { return m_vector.x; }
     Scalar y() const { return m_vector.y; }
     Scalar z() const { return m_vector.z; }
 
+    // Vector arithmetic
+
     // Vector& operator=(const Vector& rhs);
     Vector& operator+=(const Vector& rhs)
       { m_vector = dmnsn_vector_add(m_vector, rhs.m_vector); return *this; }
@@ -51,12 +57,14 @@ namespace Dimension
     Vector& operator/=(Scalar rhs)
       { m_vector = dmnsn_vector_div(m_vector, rhs); return *this; }
 
+    // Get the wrapped vector
     dmnsn_vector dmnsn() const { return m_vector; }
 
   private:
     dmnsn_vector m_vector;
   };
 
+  // Wrapper for dmnsn_line
   class line
   {
   public:
@@ -70,8 +78,11 @@ namespace Dimension
     Vector n()  const { return Vector(m_line.n); }
 
     // line& operator=(const line& l);
+
+    // Get the point `t' on the line (x0 + t*n)
     Vector operator()(Scalar t) { return Vector(dmnsn_line_point(m_line, t)); }
 
+    // Get the wrapped line
     dmnsn_line dmnsn() const { return m_line; }
 
   private:
@@ -120,12 +131,14 @@ namespace Dimension
     return r;
   }
 
+  // Dot product
   inline Scalar
   dot(const Vector& lhs, const Vector& rhs)
   {
     return dmnsn_vector_dot(lhs.dmnsn(), rhs.dmnsn());
   }
 
+  // Cross product
   inline Vector
   cross(const Vector& lhs, const Vector& rhs)
   {
diff --git a/libdimensionxx/dimensionxx/png.hpp b/libdimensionxx/dimensionxx/png.hpp
index 96ab2ca..c14b25f 100644
--- a/libdimensionxx/dimensionxx/png.hpp
+++ b/libdimensionxx/dimensionxx/png.hpp
@@ -21,25 +21,43 @@
 #ifndef DIMENSIONXX_PNG_HPP
 #define DIMENSIONXX_PNG_HPP
 
+// C++ wrapper for libdimension-png.  PNG_Canvas derives from Canvas.
+
 #include <istream>
 #include <ostream>
 
 namespace Dimension
 {
+  // PNG_Canvas handles reading a Canvas from a PNG file, writing one to a PNG
+  // file, or both, depending on what type of stream(s) are given to the
+  // constructor.
   class PNG_Canvas : public Canvas
   {
   public:
+    // Input PNG_Canvas; read the Canvas from istr now
     explicit PNG_Canvas(std::istream& istr)
       : Canvas(), m_istr(&istr), m_ostr(0), m_written(false) { read(); }
+
+    // Output PNG_Canvas; write the Canvas to ostr at destruction, or when
+    // write() is called.
     PNG_Canvas(unsigned int x, unsigned int y, std::ostream& ostr)
       : Canvas(x, y), m_istr(0), m_ostr(&ostr), m_written(false) { }
+
+    // I/O PNG_Canvas; read the Canvas from istr now, and write to ostr at
+    // destruction or then write() is called.
     PNG_Canvas(std::istream& istr, std::ostream& ostr)
       : Canvas(), m_istr(&istr), m_ostr(&ostr), m_written(false) { read(); }
+
+    // Call write() if we're an output PNG_Canvas, but trap any exceptions and
+    // report a dmnsn_error() instead.
     virtual ~PNG_Canvas();
 
+    // Write the Canvas to the output stream, throwing a Dimension_Error on
+    // error.
     void write();
 
   protected:
+    // In case a derived class needs to set m_canvas after we're constructed
     PNG_Canvas(std::ostream* ostr)
       : Canvas(), m_istr(0), m_ostr(ostr), m_written(false) { }
 
@@ -48,6 +66,8 @@ namespace Dimension
     std::ostream* m_ostr;
     bool m_written;
 
+    // Read the Canvas from a PNG file, and throw a Dimension_Error upon
+    // failure.
     void read();
 
     // Copying prohibited