Comment tweaks.

13 files changed, 69 insertions, 11 deletions

diff --git a/src/argb_frame.cc b/src/argb_frame.cc
index 7a9ad2b9..8e54e3b4 100644
--- a/src/argb_frame.cc
+++ b/src/argb_frame.cc
@@ -21,6 +21,11 @@
 
 using namespace libdcp;
 
+/** Construct an empty ARGBFrame with a given width and height and with
+ *  undefined contents.
+ *  @param width Width in pixels.
+ *  @param height Height in pixels.
+ */
 ARGBFrame::ARGBFrame (int width, int height)
 	: _width (width)
 	, _height (height)
@@ -34,6 +39,7 @@ ARGBFrame::~ARGBFrame ()
 	delete[] _data;
 }
 
+/** @return The stride, in bytes; that is, the number of bytes per row of the image */
 int
 ARGBFrame::stride () const
 {
diff --git a/src/asset_map.h b/src/asset_map.h
index 10a0915f..8cf89b4b 100644
--- a/src/asset_map.h
+++ b/src/asset_map.h
@@ -27,6 +27,9 @@
 
 namespace libdcp {
 
+/** @class Chunk
+ *  @brief A simple parser for and representation of a \<Chunk\> node within an asset map.
+ */
 class Chunk : public XMLNode
 {
 public:
@@ -39,6 +42,9 @@ public:
 	int64_t length;
 };
 
+/** @class AssetMapAsset
+ *  @brief A simple parser for and representation of an \<AssetMap\> node within an asset map.
+ */
 class AssetMapAsset : public XMLNode
 {
 public:
@@ -50,6 +56,9 @@ public:
 	std::list<boost::shared_ptr<Chunk> > chunks;
 };
 
+/** @class AssetMap
+ *  @brief A simple parser for and representation of an asset map file.
+ */
 class AssetMap : public XMLFile
 {
 public:
diff --git a/src/cpl_file.h b/src/cpl_file.h
index 14bcafd0..67b38a0d 100644
--- a/src/cpl_file.h
+++ b/src/cpl_file.h
@@ -27,6 +27,7 @@
 
 namespace libdcp {
 
+/** @brief A simple parser for and representation of a CPL \<Picture\> node */
 class Picture : public XMLNode
 {
 public:
@@ -44,7 +45,7 @@ public:
 };
 
 
-/** CPL MainPicture node */
+/** @brief A simple parser for and representation of a CPL \<MainPicture\> node */
 class MainPicture : public Picture
 {
 public:
@@ -52,7 +53,7 @@ public:
 	MainPicture (xmlpp::Node const * node);
 };
 
-/** CPL MainStereoscopicPicture node */
+/** @brief A simple parser for and representation of a CPL \<MainStereoscopicPicture\> node */
 class MainStereoscopicPicture : public Picture
 {
 public:
@@ -60,7 +61,7 @@ public:
 	MainStereoscopicPicture (xmlpp::Node const * node);
 };
 
-/** CPL MainSound node */	
+/** @brief A simple parser for and representation of a CPL \<MainSound\> node */
 class MainSound : public XMLNode
 {
 public:
@@ -75,7 +76,7 @@ public:
 	int64_t duration;
 };
 
-/** CPL MainSubtitle node */	
+/** @brief A simple parser for and representation of a CPL \<MainSubtitle\> node */
 class MainSubtitle : public XMLNode
 {
 public:
@@ -90,7 +91,7 @@ public:
 	int64_t duration;
 };
 
-/** CPL AssetList node */	
+/** @brief A simple parser for and representation of a CPL \<AssetList\> node */
 class CPLAssetList : public XMLNode
 {
 public:
@@ -103,7 +104,7 @@ public:
 	boost::shared_ptr<MainSubtitle> main_subtitle;
 };
 
-/** CPL Reel node */	
+/** @brief A simple parser for and representation of a CPL \<Reel\> node */
 class CPLReel : public XMLNode
 {
 public:
@@ -114,7 +115,8 @@ public:
 	boost::shared_ptr<CPLAssetList> asset_list;
 };
 
-/** CPL ContentVersion node */	
+
+/** @brief A simple parser for and representation of a CPL \<ContentVersion\> node */
 class ContentVersion : public XMLNode
 {
 public:
diff --git a/src/dcp.cc b/src/dcp.cc
index 5db29beb..a5e21d9f 100644
--- a/src/dcp.cc
+++ b/src/dcp.cc
@@ -307,6 +307,12 @@ CPL::CPL (string directory, string name, ContentKind content_kind, int length, i
 	_uuid = make_uuid ();
 }
 
+/** Construct a CPL object from a XML file.
+ *  @param directory The directory containing this CPL's DCP.
+ *  @param file The CPL XML filename.
+ *  @param asset_map The corresponding asset map.
+ *  @param require_mxfs true to throw an exception if a required MXF file does not exist.
+ */
 CPL::CPL (string directory, string file, shared_ptr<const AssetMap> asset_map, bool require_mxfs)
 	: _directory (directory)
 	, _content_kind (FEATURE)
diff --git a/src/dcp.h b/src/dcp.h
index d4f6aff9..b01934de 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -45,6 +45,7 @@ class SubtitleAsset;
 class Reel;
 class AssetMap;
 
+/** @brief A CPL within a DCP */
 class CPL
 {
 public:
@@ -102,7 +103,9 @@ private:
 	/** reels */
 	std::list<boost::shared_ptr<const Reel> > _reels;
 
+	/** our UUID */
 	std::string _uuid;
+	/** a SHA1 digest of our XML */
 	mutable std::string _digest;
 };
 
@@ -181,6 +184,7 @@ private:
 
 	/** the directory that we are writing to */
 	std::string _directory;
+	/** our CPLs */
 	std::list<boost::shared_ptr<const CPL> > _cpls;
 };
 
diff --git a/src/dcp_time.cc b/src/dcp_time.cc
index c9cd751a..15ad05d4 100644
--- a/src/dcp_time.cc
+++ b/src/dcp_time.cc
@@ -217,6 +217,7 @@ libdcp::operator/ (Time a, Time const & b)
 	return float (at) / bt;
 }
 
+/** @return A string of the form h:m:s:t */
 string
 Time::to_string () const
 {
@@ -225,6 +226,7 @@ Time::to_string () const
 	return str.str ();
 }
 
+/** @return This time in ticks */
 int64_t
 Time::to_ticks () const
 {
diff --git a/src/dcp_time.h b/src/dcp_time.h
index 8033348b..48698dcc 100644
--- a/src/dcp_time.h
+++ b/src/dcp_time.h
@@ -39,7 +39,13 @@ public:
 	 *  and a frames per second count.
 	 */
 	Time (int frame, int frames_per_second);
-	
+
+	/** Construct a Time from hours, minutes, seconds and ticks.
+	 *  @param h_ Hours.
+	 *  @param m_ Minutes.
+	 *  @param s_ Seconds.
+	 *  @param t_ Ticks (where 1 tick is 4 milliseconds).
+	 */
 	Time (int h_, int m_, int s_, int t_)
 		: h (h_)
 		, m (m_)
diff --git a/src/exceptions.h b/src/exceptions.h
index 25e51c9e..4c53a66d 100644
--- a/src/exceptions.h
+++ b/src/exceptions.h
@@ -55,6 +55,7 @@ private:
 	std::string _filename;
 };
 
+/** @brief An exception related to an MXF file */
 class MXFFileError : public FileError
 {
 public:
diff --git a/src/mxf_asset.h b/src/mxf_asset.h
index 03f2aa6b..b1cb87fe 100644
--- a/src/mxf_asset.h
+++ b/src/mxf_asset.h
@@ -26,6 +26,7 @@
 namespace libdcp
 {
 
+/** @brief Parent class for assets which have MXF files */	
 class MXFAsset : public Asset
 {
 public:
diff --git a/src/reel.h b/src/reel.h
index 08a438dd..c7d3b164 100644
--- a/src/reel.h
+++ b/src/reel.h
@@ -27,6 +27,7 @@ class PictureAsset;
 class SoundAsset;	
 class SubtitleAsset;	
 
+/** @brief A reel within a DCP; the part which actually contains picture, sound and subtitle data */	
 class Reel
 {
 public:
diff --git a/src/types.cc b/src/types.cc
index a00e8261..ac01ae45 100644
--- a/src/types.cc
+++ b/src/types.cc
@@ -49,6 +49,10 @@ Color::Color (int r_, int g_, int b_)
 
 }
 
+/** Construct a Color from an ARGB hex string; the alpha value is ignored.
+ *  @param argb_hex A string of the form AARRGGBB, where e.g. RR is a two-character
+ *  hex value.
+ */
 Color::Color (string argb_hex)
 {
 	int alpha;
@@ -57,6 +61,9 @@ Color::Color (string argb_hex)
 	}
 }
 
+/** @return An ARGB string of the form AARRGGBB, where e.g. RR is a two-character
+ *  hex value.  The alpha value will always be FF (ie 255; maximum alpha).
+ */
 string
 Color::to_argb_string () const
 {
@@ -72,12 +79,20 @@ Color::to_argb_string () const
 	return t;
 }
 
+/** operator== for Colors.
+ *  @param a First color to compare.
+ *  @param b Second color to compare.
+ */
 bool
 libdcp::operator== (Color const & a, Color const & b)
 {
 	return (a.r == b.r && a.g == b.g && a.b == b.b);
 }
 
+/** operator!= for Colors.
+ *  @param a First color to compare.
+ *  @param b Second color to compare.
+ */
 bool
 libdcp::operator!= (Color const & a, Color const & b)
 {
diff --git a/src/types.h b/src/types.h
index 433a910c..f1b5f640 100644
--- a/src/types.h
+++ b/src/types.h
@@ -105,6 +105,9 @@ struct EqualityOptions {
 	int max_audio_sample_error;
 };
 
+/** @class Color
+ *  @brief An RGB color (aka colour).
+ */
 class Color
 {
 public:
@@ -112,9 +115,9 @@ public:
 	Color (int r_, int g_, int b_);
 	Color (std::string argb_hex);
 
-	int r;
-	int g;
-	int b;
+	int r; ///< red component, from 0 to 255
+	int g; ///< green component, from 0 to 255
+	int b; ///< blue component, from 0 to 255
 
 	std::string to_argb_string () const;
 };
diff --git a/src/xml.h b/src/xml.h
index acace846..6fc0d0fa 100644
--- a/src/xml.h
+++ b/src/xml.h
@@ -18,6 +18,7 @@ namespace xmlpp {
 
 namespace libdcp {
 
+/** @brief A helper class for XML nodes */
 class XMLNode
 {
 public:
@@ -86,6 +87,7 @@ private:
 	std::list<Glib::ustring> _taken;
 };
 
+/** @brief A helper class for XML files */	
 class XMLFile : public XMLNode
 {
 public: