Add some comments.

1 files changed, 18 insertions, 1 deletions

diff --git a/libdimensionxx/png.cpp b/libdimensionxx/png.cpp
index 1ca3047..348b7a7 100644
--- a/libdimensionxx/png.cpp
+++ b/libdimensionxx/png.cpp
@@ -25,6 +25,9 @@
 
 namespace Dimension
 {
+  // PNG_Canvas destructor.  Call write() to write the PNG file if not already
+  // written, but catch any exceptions and instead report the error with
+  // dmnsn_error() to avoid throwing from a destructor.
   PNG_Canvas::~PNG_Canvas()
   {
     if (m_ostr && !m_written) {
@@ -37,46 +40,60 @@ namespace Dimension
     }
   }
 
+  // Write the PNG file.  Uses the fcookie() interface to make a FILE*
+  // corresponding to an std::ostream (including std::ostringstream, etc).
   void PNG_Canvas::write()
   {
     if (m_written) {
+      // Does writing a PNG file twice make sense?
       throw Dimension_Error("Attempt to write canvas to PNG twice.");
     }
 
     if (!m_ostr) {
+      // Don't call write() if we're not an output PNG_Canvas...
       throw Dimension_Error("Attempt to write canvas to PNG without an output"
                             " stream.");
     }      
 
     FILE* file = fcookie(*m_ostr);
     if (!file) {
+      // fcookie() shouldn't fail, really
       throw Dimension_Error("Couldn't create C++/C IO interface when writing"
                             " canvas to PNG.");
     }      
 
+    // Write the PNG file
     if (dmnsn_png_write_canvas(m_canvas, file)) {
+      // The actual write operation failed, for some reason.
       std::fclose(file);
       throw Dimension_Error("Writing canvas to PNG failed.");
     }
 
     std::fclose(file);
-    m_written = true;
+    m_written = true; // We've written the file now, don't do it again
   }
 
+  // Read a canvas from a  PNG file.  Uses the fcookie() interface to make a
+  // FILE* corresponding to an std::istream (including std::istringstream, etc).
   void PNG_Canvas::read()
   {
     if (!m_istr) {
+      // read() is private, and only called from the appropriate constructors,
+      // so this REALLY shouldn't happen.
       throw Dimension_Error("Attempt to read canvas from PNG without an input"
                             " stream.");
     }      
 
     FILE* file = fcookie(*m_istr);
     if (!file) {
+      // fcookie() shouldn't fail, really
       throw Dimension_Error("Couldn't create C++/C IO interface when reading"
                             " canvas from PNG.");
     }      
 
+    // Read the canvas from a PNG file
     if (!(m_canvas = dmnsn_png_read_canvas(file))) {
+      // The read operation failed
       std::fclose(file);
       throw Dimension_Error("Reading canvas from PNG failed.");
     }