Comments / tweaks.

21 files changed, 144 insertions, 16 deletions

diff --git a/src/file.cc b/src/file.cc
index d39f93e0..aabda166 100644
--- a/src/file.cc
+++ b/src/file.cc
@@ -17,11 +17,18 @@
 
 */
 
+/** @file  src/file.cc
+ *  @brief File class.
+ */
+
 #include "file.h"
 #include "util.h"
 
 using namespace dcp;
 
+/** Read a file into memory.
+ *  @param file to read.
+ */
 File::File (boost::filesystem::path file)
 {
 	_size = boost::filesystem::file_size (file);
@@ -32,6 +39,7 @@ File::File (boost::filesystem::path file)
 	fclose (f);
 }
 
+/** File destructor */
 File::~File ()
 {
 	delete[] _data;
diff --git a/src/file.h b/src/file.h
index f2b99209..b06cece0 100644
--- a/src/file.h
+++ b/src/file.h
@@ -17,10 +17,20 @@
 
 */
 
+/** @file  src/file.h
+ *  @brief File class.
+ */
+
+#ifndef LIBDCP_FILE_H
+#define LIBDCP_FILE_H
+
 #include <boost/filesystem.hpp>
 
 namespace dcp {
 
+/** @class File
+ *  @brief Helper class which loads a file into memory.
+ */
 class File
 {
 public:
@@ -36,8 +46,10 @@ public:
 	}
 
 private:
-	uint8_t* _data;
-	int64_t _size;
+	uint8_t* _data; ///< file's data
+	int64_t _size;  ///< data size in bytes
 };
 
 }
+
+#endif
diff --git a/src/mono_picture_mxf_writer.cc b/src/mono_picture_mxf_writer.cc
index b32a79f5..5cc424e1 100644
--- a/src/mono_picture_mxf_writer.cc
+++ b/src/mono_picture_mxf_writer.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/mono_picture_mxf_writer.cc
+ *  @brief MonoPictureMXFWriter class
+ */
+
 #include "AS_DCP.h"
 #include "KM_fileio.h"
 #include "mono_picture_mxf_writer.h"
diff --git a/src/mono_picture_mxf_writer.h b/src/mono_picture_mxf_writer.h
index a5e0b1b6..065171c2 100644
--- a/src/mono_picture_mxf_writer.h
+++ b/src/mono_picture_mxf_writer.h
@@ -17,6 +17,13 @@
 
 */
 
+/** @file  src/mono_picture_mxf_writer.h
+ *  @brief MonoPictureMXFWriter class
+ */
+
+#ifndef LIBDCP_MONO_PICTURE_MXF_WRITER_H
+#define LIBDCP_MONO_PICTURE_MXF_WRITER_H
+
 #include "picture_mxf_writer.h"
 #include <boost/shared_ptr.hpp>
 #include <boost/utility.hpp>
@@ -26,7 +33,8 @@
 
 namespace dcp {
 
-/** A helper class for writing to MonoPictureMXFs.
+/** @class MonoPictureMXFWriter
+ *  @brief A helper class for writing to MonoPictureMXFs
  *
  *  Objects of this class can only be created with MonoPictureMXF::start_write().
  *
@@ -57,3 +65,5 @@ private:
 };
 
 }
+
+#endif
diff --git a/src/picture_mxf_writer.h b/src/picture_mxf_writer.h
index f8c67ba9..d1baa7ad 100644
--- a/src/picture_mxf_writer.h
+++ b/src/picture_mxf_writer.h
@@ -17,6 +17,13 @@
 
 */
 
+/** @file  src/picture_mxf_writer.h
+ *  @brief PictureMXFWriter and FrameInfo classes.
+ */
+
+#ifndef LIBDCP_PICTURE_MXF_WRITER_H
+#define LIBDCP_PICTURE_MXF_WRITER_H
+
 #include "metadata.h"
 #include "types.h"
 #include "mxf_writer.h"
@@ -30,7 +37,9 @@ namespace dcp {
 
 class PictureMXF;	
 
-/** Information about a single frame (either a monoscopic frame or a left *or* right eye stereoscopic frame) */	
+/** @class FrameInfo
+ *  @brief Information about a single frame (either a monoscopic frame or a left *or* right eye stereoscopic frame)
+ */
 struct FrameInfo
 {
 	FrameInfo (uint64_t o, uint64_t s, std::string h)
@@ -50,6 +59,9 @@ struct FrameInfo
 	std::string hash;
 };
 
+/** @class PictureMXFWriter
+ *  @brief Parent class for classes which write picture MXF files.
+ */
 class PictureMXFWriter : public MXFWriter
 {
 public:
@@ -69,3 +81,5 @@ protected:
 };
 
 }
+
+#endif
diff --git a/src/reel_asset.h b/src/reel_asset.h
index b5e0537c..a71290ae 100644
--- a/src/reel_asset.h
+++ b/src/reel_asset.h
@@ -82,7 +82,7 @@ public:
 	}
 
 protected:
-	/** @return the node name that this asset uses in the CPL's <Reel> node
+	/** @return the node name that this asset uses in the CPL's &lt;Reel&gt; node
 	 *  e.g. MainPicture, MainSound etc.
 	 */
 	virtual std::string cpl_node_name () const = 0;
diff --git a/src/reel_mono_picture_asset.cc b/src/reel_mono_picture_asset.cc
index 1a5d256d..b4ed6301 100644
--- a/src/reel_mono_picture_asset.cc
+++ b/src/reel_mono_picture_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_mono_picture_asset.cc
+ *  @brief ReelMonoPictureAsset class.
+ */
+
 #include "reel_mono_picture_asset.h"
 #include "mono_picture_mxf.h"
 #include <libcxml/cxml.h>
diff --git a/src/reel_mono_picture_asset.h b/src/reel_mono_picture_asset.h
index 881bbec0..a25550a4 100644
--- a/src/reel_mono_picture_asset.h
+++ b/src/reel_mono_picture_asset.h
@@ -17,12 +17,22 @@
 
 */
 
+/** @file  src/reel_mono_picture_asset.h
+ *  @brief ReelMonoPictureAsset class.
+ */
+
+#ifndef LIBDCP_REEL_MONO_PICTURE_ASSET_H
+#define LIBDCP_REEL_MONO_PICTURE_ASSET_H
+
 #include "reel_picture_asset.h"
 
 namespace dcp {
 
 class MonoPictureMXF;	
 
+/** @class ReelMonoPictureAsset
+ *  @brief Part of a Reel's description which refers to a monoscopic picture MXF.
+ */
 class ReelMonoPictureAsset : public ReelPictureAsset
 {
 public:
@@ -36,5 +46,4 @@ private:
 
 }
 
-	
-		
+#endif
diff --git a/src/reel_picture_asset.cc b/src/reel_picture_asset.cc
index 673eb133..d1910bb3 100644
--- a/src/reel_picture_asset.cc
+++ b/src/reel_picture_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_picture_asset.h
+ *  @brief ReelPictureAsset class.
+ */
+
 #include "content.h"
 #include "reel_picture_asset.h"
 #include "picture_mxf.h"
diff --git a/src/reel_picture_asset.h b/src/reel_picture_asset.h
index b433ff88..547f3ada 100644
--- a/src/reel_picture_asset.h
+++ b/src/reel_picture_asset.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_picture_asset.h
+ *  @brief ReelPictureAsset class.
+ */
+
 #ifndef LIBDCP_REEL_PICTURE_ASSET_H
 #define LIBDCP_REEL_PICTURE_ASSET_H
 
@@ -25,6 +29,9 @@
 
 namespace dcp {
 
+/** @class ReelPictureAsset
+ *  @brief Part of a Reel's description which refers to a picture MXF.
+ */
 class ReelPictureAsset : public ReelAsset
 {
 public:
diff --git a/src/reel_sound_asset.cc b/src/reel_sound_asset.cc
index b3bc049f..984434dd 100644
--- a/src/reel_sound_asset.cc
+++ b/src/reel_sound_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_sound_asset.cc
+ *  @brief ReelSoundAsset class.
+ */
+
 #include "reel_sound_asset.h"
 #include <libcxml/cxml.h>
 
diff --git a/src/reel_sound_asset.h b/src/reel_sound_asset.h
index 27d2499f..fb233016 100644
--- a/src/reel_sound_asset.h
+++ b/src/reel_sound_asset.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_sound_asset.h
+ *  @brief ReelSoundAsset class.
+ */
+
 #include "reel_asset.h"
 #include "sound_mxf.h"
 #include <boost/shared_ptr.hpp>
@@ -24,6 +28,9 @@
 
 namespace dcp {
 
+/** @class ReelSoundAsset
+ *  @brief Part of a Reel's description which refers to a sound MXF.
+ */
 class ReelSoundAsset : public ReelAsset
 {
 public:
diff --git a/src/reel_stereo_picture_asset.cc b/src/reel_stereo_picture_asset.cc
index 0df61175..09178dc2 100644
--- a/src/reel_stereo_picture_asset.cc
+++ b/src/reel_stereo_picture_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_stereo_picture_asset.cc
+ *  @brief ReelStereoPictureAsset class.
+ */
+
 #include "reel_stereo_picture_asset.h"
 #include "stereo_picture_mxf.h"
 #include <libcxml/cxml.h>
diff --git a/src/reel_stereo_picture_asset.h b/src/reel_stereo_picture_asset.h
index 56e357be..57cc4da1 100644
--- a/src/reel_stereo_picture_asset.h
+++ b/src/reel_stereo_picture_asset.h
@@ -17,12 +17,22 @@
 
 */
 
+/** @file  src/reel_stereo_picture_asset.h
+ *  @brief ReelStereoPictureAsset class.
+ */
+
+#ifndef LIBDCP_REEL_STEREO_PICTURE_ASSET_H
+#define LIBDCP_REEL_STEREO_PICTURE_ASSET_H
+
 #include "reel_picture_asset.h"
 
 namespace dcp {
 
 class StereoPictureMXF;	
 
+/** @class ReelStereoPictureAsset
+ *  @brief Part of a Reel's description which refers to a stereoscopic picture MXF.
+ */
 class ReelStereoPictureAsset : public ReelPictureAsset
 {
 public:
@@ -37,5 +47,5 @@ private:
 
 }
 
-	
-		
+#endif
+
diff --git a/src/reel_subtitle_asset.cc b/src/reel_subtitle_asset.cc
index b2e46f93..1c948200 100644
--- a/src/reel_subtitle_asset.cc
+++ b/src/reel_subtitle_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/reel_subtitle_asset.cc
+ *  @brief ReelSubtitleAsset class.
+ */
+
 #include "subtitle_content.h"
 #include "reel_subtitle_asset.h"
 
diff --git a/src/reel_subtitle_asset.h b/src/reel_subtitle_asset.h
index 429c9859..5cdfac13 100644
--- a/src/reel_subtitle_asset.h
+++ b/src/reel_subtitle_asset.h
@@ -17,12 +17,22 @@
 
 */
 
+/** @file  src/reel_subtitle_asset.h
+ *  @brief ReelSubtitleAsset class.
+ */
+
+#ifndef LIBDCP_REEL_SUBTITLE_ASSET_H
+#define LIBDCP_REEL_SUBTITLE_ASSET_H
+
 #include "reel_asset.h"
 
 namespace dcp {
 
 class SubtitleContent;
 
+/** @class ReelSubtitleAsset
+ *  @brief Part of a Reel's description which refers to a subtitle XML file.
+ */
 class ReelSubtitleAsset : public ReelAsset
 {
 public:
@@ -38,3 +48,5 @@ private:
 };
 
 }
+
+#endif
diff --git a/src/sound_frame.cc b/src/sound_frame.cc
index 6471ee0a..da0da194 100644
--- a/src/sound_frame.cc
+++ b/src/sound_frame.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/sound_frame.cc
+ *  @brief SoundFrame class.
+ */
+
 #include "sound_frame.h"
 #include "exceptions.h"
 #include "AS_DCP.h"
@@ -25,10 +29,10 @@
 using namespace std;
 using namespace dcp;
 
-SoundFrame::SoundFrame (string mxf_path, int n, ASDCP::AESDecContext* c)
+SoundFrame::SoundFrame (boost::filesystem::path mxf_path, int n, ASDCP::AESDecContext* c)
 {
 	ASDCP::PCM::MXFReader reader;
-	Kumu::Result_t r = reader.OpenRead (mxf_path.c_str());
+	Kumu::Result_t r = reader.OpenRead (mxf_path.file().c_str());
 	if (ASDCP_FAILURE (r)) {
 		boost::throw_exception (FileError ("could not open MXF file for reading", mxf_path, r));
 	}
diff --git a/src/sound_frame.h b/src/sound_frame.h
index e7b13885..de58a034 100644
--- a/src/sound_frame.h
+++ b/src/sound_frame.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/sound_frame.h
+ *  @brief SoundFrame class.
+ */
+
 #ifndef LIBDCP_SOUND_FRAME_H
 #define LIBDCP_SOUND_FRAME_H
 
@@ -33,16 +37,20 @@ namespace ASDCP {
 
 namespace dcp {
 
+/** @class SoundFrame
+ *  @brief One &lsquo;frame&rsquo; of sound data from a MXF.
+ */
 class SoundFrame : public boost::noncopyable
 {
 public:
-	SoundFrame (std::string mxf_path, int n, ASDCP::AESDecContext *);
+	SoundFrame (boost::filesystem::path mxf_path, int n, ASDCP::AESDecContext *);
 	~SoundFrame ();
 
 	uint8_t const * data () const;
 	int size () const;
 
 private:
+	/** a buffer to hold the frame */
 	ASDCP::PCM::FrameBuffer* _buffer;
 };
 
diff --git a/src/sound_mxf.cc b/src/sound_mxf.cc
index f6613867..fa48a6c1 100644
--- a/src/sound_mxf.cc
+++ b/src/sound_mxf.cc
@@ -161,7 +161,7 @@ shared_ptr<const SoundFrame>
 SoundMXF::get_frame (int n) const
 {
 	/* XXX: should add on entry point here? */
-	return shared_ptr<const SoundFrame> (new SoundFrame (file().string(), n, _decryption_context));
+	return shared_ptr<const SoundFrame> (new SoundFrame (file(), n, _decryption_context));
 }
 
 shared_ptr<SoundMXFWriter>
diff --git a/src/util.h b/src/util.h
index 8db838eb..2bfeb60a 100644
--- a/src/util.h
+++ b/src/util.h
@@ -45,6 +45,9 @@ class CertificateChain;
 class GammaLUT;
 class XYZFrame;
 
+/** @struct Size
+ *  @brief The integer, two-dimensional size of something.
+ */
 struct Size
 {
 	Size ()
diff --git a/src/xyz_frame.h b/src/xyz_frame.h
index fcaae891..8ba829b2 100644
--- a/src/xyz_frame.h
+++ b/src/xyz_frame.h
@@ -26,10 +26,10 @@
 
 namespace dcp {
 
-/* @class XYZFrame
- * @brief An image in XYZ colour.
+/** @class XYZFrame
+ *  @brief An image in XYZ colour.
  *
- * This class is a thin wrapper of libopenjpeg's opj_image_t.
+ *  This class is a thin wrapper of libopenjpeg's opj_image_t.
  */
 class XYZFrame : public boost::noncopyable
 {