Small bits of tidying up and comments.

10 files changed, 85 insertions, 24 deletions

diff --git a/src/argb_frame.h b/src/argb_frame.h
index a1b3b427..419227bb 100644
--- a/src/argb_frame.h
+++ b/src/argb_frame.h
@@ -48,13 +48,15 @@ public:
 	ARGBFrame (Size size);
 	~ARGBFrame ();
 
+	/** @return pointer to the image data */
 	uint8_t* data () const {
 		return _data;
 	}
 
-	/** Length of one picture row in bytes */
+	/** @return length of one picture row in bytes */
 	int stride () const;
 
+	/** @return size of the picture in pixels */
 	Size size () const {
 		return _size;
 	}
diff --git a/src/asset.h b/src/asset.h
index bd172428..e6a302c1 100644
--- a/src/asset.h
+++ b/src/asset.h
@@ -48,7 +48,6 @@ public:
 	Asset (boost::filesystem::path file);
 	Asset (std::string id);
 
-	virtual std::string pkl_type () const = 0;
 	virtual bool equals (
 		boost::shared_ptr<const Asset> other,
 		EqualityOptions opt,
@@ -77,6 +76,8 @@ public:
 	std::string hash () const;
 
 protected:
+	virtual std::string pkl_type () const = 0;
+	
 	/** The disk file that represents this asset, if one exists */
 	mutable boost::filesystem::path _file;
 	/** Hash of _file, or empty if the hash has not yet been computed */
diff --git a/src/cpl.cc b/src/cpl.cc
index fc1b878c..215640d3 100644
--- a/src/cpl.cc
+++ b/src/cpl.cc
@@ -103,6 +103,12 @@ CPL::add (boost::shared_ptr<Reel> reel)
 	_reels.push_back (reel);
 }
 
+/** Write an CompositonPlaylist XML file.
+ *  @param file Filename to write.
+ *  @param standard INTEROP or SMPTE.
+ *  @param metadata Metadata to use.
+ *  @param signer Signer to sign the CPL, or 0 to add no signature.
+ */
 void
 CPL::write_xml (boost::filesystem::path file, Standard standard, XMLMetadata metadata, shared_ptr<const Signer> signer) const
 {
@@ -214,6 +220,10 @@ CPL::encrypted () const
 	return false;
 }
 
+/** Add a KDM to this CPL.  If the KDM is for any of this CPLs assets it will be used
+ *  to decrypt those assets.
+ *  @param kdm KDM.
+ */
 void
 CPL::add (KDM const & kdm)
 {
diff --git a/src/cpl.h b/src/cpl.h
index f695e4e2..d28737e1 100644
--- a/src/cpl.h
+++ b/src/cpl.h
@@ -50,10 +50,6 @@ public:
 	CPL (std::string annotation_text, ContentKind content_kind);
 	CPL (boost::filesystem::path file);
 
-	std::string pkl_type () const {
-		return "text/xml";
-	}
-
 	bool equals (
 		CPL const & other,
 		EqualityOptions options,
@@ -62,19 +58,23 @@ public:
 
 	void add (boost::shared_ptr<Reel> reel);
 	void add (KDM const &);
-	
+
+	/** @return contents of the <AnnotationText> node */
 	std::string annotation_text () const {
 		return _annotation_text;
 	}
 	
+	/** @return contents of the <ContentTitleText> node */
 	std::string content_title_text () const {
 		return _content_title_text;
 	}
 
+	/** @return contents of the <Id> node within <ContentVersion> */
 	void set_content_version_id (std::string id) {
 		_content_version_id = id;
 	}
 
+	/** @return contents of the <LabelText> node within <ContentVersion> */
 	void set_content_version_label_text (std::string text) {
 		_content_version_label_text = text;
 	}
@@ -86,10 +86,14 @@ public:
 		return _content_kind;
 	}
 
+	/** @return the reels in this CPL */
 	std::list<boost::shared_ptr<Reel> > reels () const {
 		return _reels;
 	}
 
+	/** @return the Content in this CPL across all its reels
+	 *  (Content is picture, sound and subtitles)
+	 */
 	std::list<boost::shared_ptr<const Content> > content () const;
 
 	bool encrypted () const;
@@ -104,7 +108,13 @@ public:
 		) const;
 
 	void resolve_refs (std::list<boost::shared_ptr<Object> >);
-	
+
+protected:
+	/** @return type string for PKLs for this asset */
+	std::string pkl_type () const {
+		return "text/xml";
+	}
+
 private:
 	std::string _annotation_text;               ///< <AnnotationText>
 	std::string _issue_date;                    ///< <IssueDate>
diff --git a/src/exceptions.h b/src/exceptions.h
index c1d47e51..bc5e83d1 100644
--- a/src/exceptions.h
+++ b/src/exceptions.h
@@ -29,7 +29,9 @@
 namespace dcp
 {
 
-/** @brief An exception related to a file */
+/** @class FileError
+ *  @brief An exception related to a file
+ */
 class FileError : public std::exception
 {
 public:
@@ -59,7 +61,9 @@ private:
 	int _number;
 };
 
-/** @brief An exception related to an MXF file */
+/** @class MXFFileError
+ *  @brief An exception related to an MXF file
+ */
 class MXFFileError : public FileError
 {
 public:
@@ -68,7 +72,9 @@ public:
 	{}
 };
 	
-/** @brief A miscellaneous exception */
+/** @class MiscError
+ *  @brief A miscellaneous exception
+ */
 class MiscError : public std::exception
 {
 public:
@@ -85,7 +91,9 @@ private:
 	std::string _message;
 };
 
-/** @brief A DCP read exception */
+/** @class DCPReadError
+ *  @brief A DCP read exception
+ */
 class DCPReadError : public std::exception
 {
 public:
@@ -102,7 +110,9 @@ private:
 	std::string _message;
 };
 
-/** @brief An XML error */
+/** @class XMLError
+ *  @brief An XML error
+ */
 class XMLError : public std::exception
 {
 public:
@@ -119,6 +129,9 @@ private:
 	std::string _message;
 };
 
+/** @class UnresolvedRefError
+ *  @brief An exception caused by a reference (by UUID) to something which is not known
+ */
 class UnresolvedRefError : public std::exception
 {
 public:
diff --git a/src/metadata.h b/src/metadata.h
index e1ce6986..b1fcdd8e 100644
--- a/src/metadata.h
+++ b/src/metadata.h
@@ -31,6 +31,9 @@ class utc_offset_to_string_test;
 namespace dcp
 {
 
+/** @class MXFMetadata
+ *  @brief Metadata that is written to a MXF file's header
+ */
 class MXFMetadata
 {
 public:
@@ -41,6 +44,9 @@ public:
 	std::string product_version;
 };
 
+/** @class XMLMetadata
+ *  @brief Common metadata that is written to a few different XML files
+ */
 class XMLMetadata
 {
 public:
diff --git a/src/mxf.h b/src/mxf.h
index f7336fee..66fb536f 100644
--- a/src/mxf.h
+++ b/src/mxf.h
@@ -47,10 +47,6 @@ public:
 
 	virtual std::string key_type () const = 0;
 	
-	std::string pkl_type () const {
-		return "application/x-smpte-mxf";
-	}
-	
 	bool equals (
 		boost::shared_ptr<const Content> other,
 		EqualityOptions opt,
@@ -98,6 +94,10 @@ public:
 	}
 
 protected:
+	std::string pkl_type () const {
+		return "application/x-smpte-mxf";
+	}
+	
 	void read_writer_info (ASDCP::WriterInfo const &);
 	
 	/** Signal to emit to report progress, or 0 */
diff --git a/src/subtitle_content.h b/src/subtitle_content.h
index 476f8fe4..c4d0012b 100644
--- a/src/subtitle_content.h
+++ b/src/subtitle_content.h
@@ -42,10 +42,6 @@ public:
 	SubtitleContent (boost::filesystem::path file);
 	SubtitleContent (Fraction edit_rate, std::string movie_title, std::string language);
 
-	std::string pkl_type () const {
-		return "text/xml";
-	}
-	
 	bool equals (
 		boost::shared_ptr<const Content>,
 		EqualityOptions,
@@ -70,6 +66,11 @@ public:
 	void write_xml () const;
 	Glib::ustring xml_as_string () const;
 
+protected:
+	std::string pkl_type () const {
+		return "text/xml";
+	}
+	
 private:
 	std::string font_id_to_name (std::string id) const;
 
diff --git a/src/types.h b/src/types.h
index 0a3860a8..ece7d44c 100644
--- a/src/types.h
+++ b/src/types.h
@@ -107,8 +107,16 @@ public:
 
 extern bool operator== (Fraction const & a, Fraction const & b);
 extern bool operator!= (Fraction const & a, Fraction const & b);
-	
-struct EqualityOptions {
+
+/** @struct EqualityOptions
+ *  @brief  A class to describe what "equality" means for a particular test.
+ *
+ *  When comparing things, we want to be able to ignore some differences;
+ *  this class expresses those differences.
+ */
+struct EqualityOptions
+{
+	/** Construct an EqualityOptions where nothing at all can differ */
 	EqualityOptions () 
 		: max_mean_pixel_error (0)
 		, max_std_dev_pixel_error (0)
@@ -117,10 +125,15 @@ struct EqualityOptions {
 		, mxf_names_can_differ (false)
 	{}
 
+	/** The maximum allowable mean difference in pixel value between two images */
 	double max_mean_pixel_error;
+	/** The maximum standard deviation of the differences in pixel value between two images */
 	double max_std_dev_pixel_error;
+	/** The maximum difference in audio sample value between two soundtracks */
 	int max_audio_sample_error;
+	/** true if the <AnnotationText> nodes of CPLs are allowed to differ */
 	bool cpl_annotation_texts_can_differ;
+	/** true if MXF filenames are allowed to differ */
 	bool mxf_names_can_differ;
 };
 
diff --git a/src/xyz_frame.h b/src/xyz_frame.h
index 5319f9d4..fcaae891 100644
--- a/src/xyz_frame.h
+++ b/src/xyz_frame.h
@@ -28,6 +28,8 @@ namespace dcp {
 
 /* @class XYZFrame
  * @brief An image in XYZ colour.
+ *
+ * This class is a thin wrapper of libopenjpeg's opj_image_t.
  */
 class XYZFrame : public boost::noncopyable
 {
@@ -39,12 +41,15 @@ public:
 	int* data (int) const;
 	dcp::Size size () const;
 
+	/** @return Pointer to opj_image_t struct.  The caller
+	 *  must not delete this.
+	 */
 	opj_image_t* opj_image () const {
 		return _opj_image;
 	}
 
 private:
-	opj_image_t* _opj_image;
+	opj_image_t* _opj_image; ///< opj_image_t that we are managing
 };
 
 }