Small bits of tidying up and comments.

diff --git a/src/argb_frame.h b/src/argb_frame.h
index a1b3b4276da68c8ee290533c3ac76bc28486fcd3..419227bbbb19bd1504d18ae661db4cbd9944d831 100644 (file)
--- 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 bd172428cc78249b28363a9cd8a598a91404036d..e6a302c15010be3fccfd977cfb13fa6caba5927f 100644 (file)
--- 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 fc1b878c68896caa868142a98578c773015155a7..215640d316b29b5598ea1403d3d9dff14d7f8720 100644 (file)
--- 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 f695e4e22106b1eaafa88d7cc2bf12965f82f082..d28737e146e6acfad57f6d969c0ae19f9833f6f7 100644 (file)
--- 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 c1d47e51b6588ff04662eea9c08986073461280d..bc5e83d17e3855326799650ef31037aa3ea34715 100644 (file)
--- 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 e1ce6986fb00ad61e984bb445979d75acc34d83f..b1fcdd8e9936ea89836fdedb37772bf1b7dc3efa 100644 (file)
--- 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 f7336fee56d660810328414516828f838452d402..66fb536f56041edae38fd5d2aaf1d757489cc17a 100644 (file)
--- 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 476f8fe480c07c515aa5a74ee1a1295db1be938a..c4d0012bc9f7cbe76c08091bdb1c1f4ac7090c88 100644 (file)
--- 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 0a3860a8c5683f528a5d9296cad277f3527edddd..ece7d44c284bb547ee18764103947b887c7d8aa0 100644 (file)
--- 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 5319f9d4239608915393214f61bf1452ffb10639..fcaae891770df918bbabafa30664bae0fbeaff28 100644 (file)
--- 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
 };
 
 }