Some comments.1.0-new-asdcplib

8 files changed, 67 insertions, 3 deletions

diff --git a/src/chromaticity.h b/src/chromaticity.h
index 89b71936..1cf68248 100644
--- a/src/chromaticity.h
+++ b/src/chromaticity.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/chromaticity.h
+ *  @brief Chromaticity class.
+ */
+
 #ifndef DCP_CHROMATICITY_H
 #define DCP_CHROMATICITY_H
 
@@ -24,6 +28,9 @@
 
 namespace dcp {
 
+/** @class Chromaticity
+ *  @brief A representation of a x,y,z chromaticity, where z = 1 - x - y
+ */
 class Chromaticity
 {
 public:
@@ -36,7 +43,7 @@ public:
 		: x (x_)
 		, y (y_)
 	{}
-		
+
 	double x;
 	double y;
 
@@ -44,6 +51,7 @@ public:
 		return 1 - x - y;
 	}
 
+	/** @return true if this Chromaticity's x and y are within epsilon of other */
 	bool about_equal (Chromaticity const & other, float epsilon) const {
 		return std::fabs (x - other.x) < epsilon && std::fabs (y - other.y) < epsilon;
 	}
diff --git a/src/colour_conversion.h b/src/colour_conversion.h
index 939b0d2b..1f824c81 100644
--- a/src/colour_conversion.h
+++ b/src/colour_conversion.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/colour_conversion.h
+ *  @brief ColourConversion class.
+ */
+
 #ifndef DCP_COLOUR_CONVERSION_H
 #define DCP_COLOUR_CONVERSION_H
 
@@ -35,6 +39,10 @@ enum YUVToRGB {
 	YUV_TO_RGB_COUNT
 };
 
+/** @class ColourConversion
+ *  @brief A representation of all the parameters involved the colourspace conversion
+ *  of a YUV image to XYZ (via RGB).
+ */
 class ColourConversion
 {
 public:
@@ -132,7 +140,9 @@ public:
 	static ColourConversion const & p3_to_xyz ();
 
 protected:
+	/** Input transfer function (probably a gamma function, or something similar) */
 	boost::shared_ptr<const TransferFunction> _in;
+	/** Conversion to use from YUV to RGB */
 	YUVToRGB _yuv_to_rgb;
 	Chromaticity _red;
 	Chromaticity _green;
@@ -140,6 +150,7 @@ protected:
 	Chromaticity _white;
 	/** White point that we are adjusting to using a Bradford matrix */
 	boost::optional<Chromaticity> _adjusted_white;
+	/** Output transfer function (probably an inverse gamma function, or something similar) */
 	boost::shared_ptr<const TransferFunction> _out;
 };
 
diff --git a/src/exceptions.h b/src/exceptions.h
index 9b2617ee..e613c980 100644
--- a/src/exceptions.h
+++ b/src/exceptions.h
@@ -29,6 +29,9 @@
 namespace dcp
 {
 
+/** @class StringError
+ *  @brief An exception that uses a std::string to store its error message.
+ */
 class StringError : public std::exception
 {
 public:
@@ -159,13 +162,20 @@ public:
 	TimeFormatError (std::string bad_time);
 };
 
+/** @class NotEncryptedError
+ *  @brief An error raised when creating a DecryptedKDM object for assets that are not
+ *  encrypted.
+ */
 class NotEncryptedError : public StringError
 {
 public:
 	NotEncryptedError (std::string const & what);
 	~NotEncryptedError () throw () {}
 };
-	
+
+/** @class ProgrammingError
+ *  @brief An exception thrown when a DCP_ASSERT fails; something that should not happen.
+ */
 class ProgrammingError : public StringError
 {
 public:
diff --git a/src/load_font_node.h b/src/load_font_node.h
index 24f193bd..58e5920a 100644
--- a/src/load_font_node.h
+++ b/src/load_font_node.h
@@ -17,10 +17,17 @@
 
 */
 
+/** @file  src/load_font_node.h
+ *  @brief LoadFontNode class.
+ */
+
 #include <string>
 
 namespace dcp {
 
+/** @class LoadFontNode
+ *  @brief Parser for LoadFont nodes from subtitle XML.
+ */
 class LoadFontNode
 {
 public:
diff --git a/src/mono_picture_mxf_writer.h b/src/mono_picture_mxf_writer.h
index 065171c2..7cad54e0 100644
--- a/src/mono_picture_mxf_writer.h
+++ b/src/mono_picture_mxf_writer.h
@@ -38,7 +38,7 @@ namespace dcp {
  *
  *  Objects of this class can only be created with MonoPictureMXF::start_write().
  *
- *  Frames can be written to the MonoPictureAsset by calling write() with a JPEG2000 image
+ *  Frames can be written to the MonoPictureMXF by calling write() with a JPEG2000 image
  *  (a verbatim .j2c file).  finalize() must be called after the last frame has been written.
  *  The action of finalize() can't be done in MonoPictureAssetWriter's destructor as it may
  *  throw an exception.
diff --git a/src/smpte_load_font_node.h b/src/smpte_load_font_node.h
index 1ca7786a..a150d9be 100644
--- a/src/smpte_load_font_node.h
+++ b/src/smpte_load_font_node.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/smpte_load_font_node.h
+ *  @brief SMPTELoadFontNode class.
+ */
+
 #include "load_font_node.h"
 #include <boost/shared_ptr.hpp>
 #include <boost/optional.hpp>
@@ -27,6 +31,9 @@ namespace cxml {
 
 namespace dcp {
 	
+/** @class SMPTELoadFontNode
+ *  @brief Parser for LoadFont nodes from SMPTE subtitle XML.
+ */
 class SMPTELoadFontNode : public LoadFontNode
 {
 public:
diff --git a/src/sound_mxf_writer.h b/src/sound_mxf_writer.h
index 4f60074c..d79c60db 100644
--- a/src/sound_mxf_writer.h
+++ b/src/sound_mxf_writer.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/sound_mxf_writer.h
+ *  @brief SoundMXFWriter class.
+ */
+
 #include "mxf_writer.h"
 #include "types.h"
 #include <boost/shared_ptr.hpp>
@@ -27,6 +31,15 @@ namespace dcp {
 class SoundFrame;
 class SoundMXF;
 
+/** @class SoundMXFWriter
+ *  @brief A helper class for writing to SoundMXFs.
+ *
+ *  Objects of this class can only be created with SoundMXF::start_write().
+ *
+ *  Sound samples can be written to the SoundMXF by calling write() with
+ *  a buffer of float values.  finalize() must be called after the last samples
+ *  have been written.
+ */
 class SoundMXFWriter : public MXFWriter
 {
 public:
diff --git a/src/transfer_function.h b/src/transfer_function.h
index 7f7187b5..c8248cce 100644
--- a/src/transfer_function.h
+++ b/src/transfer_function.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/transfer_function.h
+ *  @brief TransferFunction class.
+ */
+
 #ifndef LIBDCP_TRANSFER_FUNCTION_H
 #define LIBDCP_TRANSFER_FUNCTION_H
 
@@ -27,6 +31,9 @@
 
 namespace dcp {
 
+/** @class TransferFunction
+ *  @brief A transfer function represented by a lookup table.
+ */
 class TransferFunction : public boost::noncopyable
 {
 public:
@@ -38,6 +45,7 @@ public:
 	virtual bool about_equal (boost::shared_ptr<const TransferFunction> other, double epsilon) const = 0;
 
 protected:
+	/** Make a LUT and return an array allocated by new */
 	virtual double * make_lut (int bit_depth, bool inverse) const = 0;
 
 private: