Doc fixes.

10 files changed, 225 insertions, 120 deletions

diff --git a/src/asset.cc b/src/asset.cc
index 4a44e11f..4a111a19 100644
--- a/src/asset.cc
+++ b/src/asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/asset.cc
+ *  @brief Parent class for assets of DCPs.
+ */
+
 #include <iostream>
 #include <boost/filesystem.hpp>
 #include "AS_DCP.h"
@@ -29,25 +33,16 @@ using namespace std;
 using namespace boost;
 using namespace libdcp;
 
-/** Construct an Asset.
- *  @param p Pathname of MXF file.
- *  @param fps Frames per second.
- *  @param len Length in frames.
- */
-
-Asset::Asset (string p, sigc::signal1<void, float>* progress, int fps, int len)
-	: _mxf_path (p)
+Asset::Asset (string mxf_path, sigc::signal1<void, float>* progress, int fps, int length)
+	: _mxf_path (mxf_path)
 	, _progress (progress)
 	, _fps (fps)
-	, _length (len)
+	, _length (length)
 	, _uuid (make_uuid ())
 {
 	
 }
 
-/** Write details of the asset to a PKL stream.
- *  @param s Stream.
- */
 void
 Asset::write_to_pkl (ostream& s) const
 {
@@ -60,9 +55,6 @@ Asset::write_to_pkl (ostream& s) const
 	  << "    </Asset>\n";
 }
 
-/** Write details of the asset to a ASSETMAP stream.
- *  @param s Stream.
- */
 void
 Asset::write_to_assetmap (ostream& s) const
 {
@@ -79,7 +71,6 @@ Asset::write_to_assetmap (ostream& s) const
 	  << "    </Asset>\n";
 }
 
-/** Fill in a ADSCP::WriteInfo struct */
 void
 Asset::fill_writer_info (ASDCP::WriterInfo* writer_info) const
 {
diff --git a/src/asset.h b/src/asset.h
index 2d33e069..b0cc450c 100644
--- a/src/asset.h
+++ b/src/asset.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/asset.h
+ *  @brief Parent class for assets of DCPs.
+ */
+
 #ifndef LIBDCP_ASSET_H
 #define LIBDCP_ASSET_H
 
@@ -30,18 +34,41 @@ namespace ASDCP {
 namespace libdcp
 {
 
-/** Parent class for assets (picture / sound collections) */	
+/** @brief Parent class for assets of DCPs
+ *
+ *  These are collections of pictures or sound.
+ */
 class Asset
 {
 public:
-	Asset (std::string, sigc::signal1<void, float>*, int, int);
+	/** Construct an Asset.
+	 *  @param mxf_path Pathname of MXF file.
+	 *  @param progress Signal to inform of progress.
+	 *  @param fps Frames per second.
+	 *  @param length Length in frames.
+	 */
+	Asset (std::string mxf_path, sigc::signal1<void, float>* progress, int fps, int length);
+
+	/** Write details of the asset to a CPL stream.
+	 *  @param s Stream.
+	 */
+	virtual void write_to_cpl (std::ostream& s) const = 0;
+
+	/** Write details of the asset to a PKL stream.
+	 *  @param s Stream.
+	 */
+	void write_to_pkl (std::ostream& s) const;
 
-	virtual void write_to_cpl (std::ostream &) const = 0;
-	void write_to_pkl (std::ostream &) const;
-	void write_to_assetmap (std::ostream &) const;
+	/** Write details of the asset to a ASSETMAP stream.
+	 *  @param s Stream.
+	 */
+	void write_to_assetmap (std::ostream& s) const;
 
 protected:
-	void fill_writer_info (ASDCP::WriterInfo *) const;
+	/** Fill in a ADSCP::WriteInfo struct.
+	 *  @param w struct to fill in.
+	 */
+	void fill_writer_info (ASDCP::WriterInfo* w) const;
 
 	/** Path to our MXF file */
 	std::string _mxf_path;
diff --git a/src/dcp.cc b/src/dcp.cc
index 9a7c367b..efeafb12 100644
--- a/src/dcp.cc
+++ b/src/dcp.cc
@@ -33,25 +33,16 @@ using namespace std;
 using namespace boost;
 using namespace libdcp;
 
-/** Construct a DCP.
- *  @param d Directory to write files to.
- *  @param n Name.
- *  @param c Content type.
- *  @param fps Frames per second.
- *  @param length Length in frames.
- */
-DCP::DCP (string d, string n, ContentType c, int fps, int length)
-	: _directory (d)
-	, _name (n)
-	, _content_type (c)
+DCP::DCP (string directory, string name, ContentType content_type, int fps, int length)
+	: _directory (directory)
+	, _name (name)
+	, _content_type (content_type)
 	, _fps (fps)
 	, _length (length)
 {
+	
 }
 
-/** Add a sound asset.
- *  @param files Pathnames of WAV files to use in the order Left, Right, Centre, Lfe (sub), Left surround, Right surround.
- */
 void
 DCP::add_sound_asset (list<string> const & files)
 {
@@ -61,9 +52,6 @@ DCP::add_sound_asset (list<string> const & files)
 	_assets.push_back (shared_ptr<SoundAsset> (new SoundAsset (files, p.string(), &Progress, _fps, _length)));
 }
 
-/** Add a picture asset.
- *  @param files Pathnames of JPEG2000 files, in frame order.
- */
 void
 DCP::add_picture_asset (list<string> const & files, int w, int h)
 {
@@ -73,9 +61,6 @@ DCP::add_picture_asset (list<string> const & files, int w, int h)
 	_assets.push_back (shared_ptr<PictureAsset> (new PictureAsset (files, p.string(), &Progress, _fps, _length, w, h)));
 }
 
-/** Write the required XML files to the directory that was
- *  passed into the constructor.
- */
 void
 DCP::write_xml () const
 {
@@ -91,10 +76,6 @@ DCP::write_xml () const
 	write_assetmap (cpl_uuid, cpl_length, pkl_uuid, filesystem::file_size (pkl_path));
 }
 
-/** Write the CPL file.
- *  @param cpl_uuid UUID to use.
- *  @return CPL pathname.
- */
 string
 DCP::write_cpl (string cpl_uuid) const
 {
@@ -136,12 +117,6 @@ DCP::write_cpl (string cpl_uuid) const
 	return p.string ();
 }
 
-/** Write the PKL file.
- *  @param pkl_uuid UUID to use.
- *  @param cpl_uuid UUID of the CPL file.
- *  @param cpl_digest SHA digest of the CPL file.
- *  @param cpl_length Length of the CPL file in bytes.
- */
 std::string
 DCP::write_pkl (string pkl_uuid, string cpl_uuid, string cpl_digest, int cpl_length) const
 {
@@ -178,7 +153,6 @@ DCP::write_pkl (string pkl_uuid, string cpl_uuid, string cpl_digest, int cpl_len
 	return p.string ();
 }
 
-/** Write the VOLINDEX file */
 void
 DCP::write_volindex () const
 {
@@ -193,12 +167,6 @@ DCP::write_volindex () const
 	   << "</VolumeIndex>\n";
 }
 
-/** Write the ASSETMAP file.
- *  @param cpl_uuid UUID of our CPL.
- *  @param cpl_length Length of our CPL in bytes.
- *  @param pkl_uuid UUID of our PKL.
- *  @param pkl_length Length of our PKL in bytes.
- */
 void
 DCP::write_assetmap (string cpl_uuid, int cpl_length, string pkl_uuid, int pkl_length) const
 {
@@ -249,13 +217,10 @@ DCP::write_assetmap (string cpl_uuid, int cpl_length, string pkl_uuid, int pkl_l
 	   << "</AssetMap>\n";
 }
 
-/** @param t A content type.
- *  @return A string representation suitable for use in a CPL.
- */
 string
-DCP::content_type_string (ContentType t)
+DCP::content_type_string (ContentType type)
 {
-	switch (t) {
+	switch (type) {
 	case FEATURE:
 		return "feature";
 	case SHORT:
diff --git a/src/dcp.h b/src/dcp.h
index 6170896b..b2d20c69 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -25,12 +25,54 @@
 #include <boost/shared_ptr.hpp>
 #include <sigc++/sigc++.h>
 
+/** @brief Namespace for everything in libdcp */
 namespace libdcp
 {
 
 class Asset;	
 
-/** A class to create a DCP */	
+/** @class DCP dcp.h libdcp/dcp.h
+ *  @brief A class to create a DCP.
+ *
+ *  Typical use might be:
+ *  @code
+ *  #include <libdcp/dcp.h>
+ *  using namespace std;
+ *
+ *  libdcp::DCP dcp ("My Film DCP", "My Film", libdcp::DCP::FEATURE, 24, 50000);
+ *
+ *  list<string> j2k_files;
+ *  j2k_files.push_back ("1.j2c");
+ *  ...
+ *  j2k_files.push_back ("50000.j2c");
+ *
+ *  // These images are 1998x1080 pixels (DCI Flat)
+ *  dcp.add_picture_asset (j2k_files, 1998, 1080);
+ *
+ *  list<string> wav_files;
+ *  wav_files.push_back ("L.wav");
+ *  wav_files.push_back ("R.wav");
+ *  wav_files.push_back ("C.wav");
+ *  wav_files.push_back ("Lfe.wav");
+ *  wav_files.push_back ("Ls.wav");
+ *  wav_files.push_back ("Rs.wav");
+ *  dcp.add_sound_asset (wav_files);
+ *
+ *  dcp.write_xml ();
+ *
+ *  @endcode
+ *
+ *  This will create a DCP at 24 frames per second with 50000 frames, writing
+ *  data to a directory "My Film DCP", naming the DCP "My Film" and marking
+ *  as a Feature.  We then add the picture and sound files (which creates
+ *  MXF files inside the DCP directory) and then write the required XML files.
+ *
+ *  If you want to report progress for long jobs (add_picture_asset() can
+ *  take a long time, in particular, as it must do a lot of disk I/O for
+ *  large DCPs), connect to the libdcp::DCP::Progress signal and report its parameter
+ *  to the user (it will range between 0 for 0% and 1 for 100%).
+ */
+ 
 class DCP
 {
 public:
@@ -47,12 +89,32 @@ public:
 		PUBLIC_SERVICE_ANNOUNCEMENT,
 		ADVERTISEMENT
 	};
-	
-	DCP (std::string, std::string, ContentType, int, int);
 
-	void add_sound_asset (std::list<std::string> const &);
-	void add_picture_asset (std::list<std::string> const &, int, int);
+	/** Construct a DCP.
+	 *  @param directory Directory to write files to.
+	 *  @param name Name.
+	 *  @param content_type Content type.
+	 *  @param fps Frames per second.
+	 *  @param length Length in frames.
+	 */
+	DCP (std::string directory, std::string name, ContentType content_type, int fps, int length);
+
+	/** Add a sound asset.
+	 *  @param files Pathnames of WAV files to use in the order Left, Right,
+	 *  Centre, Lfe (sub), Left surround, Right surround.
+	 */
+	void add_sound_asset (std::list<std::string> const & files);
 
+	/** Add a picture asset.
+	 *  @param files Pathnames of JPEG2000 files, in frame order.
+	 *  @param width Width of images in pixels.
+	 *  @param height Height of images in pixels.
+	 */
+	void add_picture_asset (std::list<std::string> const & files, int width, int height);
+
+	/** Write the required XML files to the directory that was
+	 *  passed into the constructor.
+	 */
 	void write_xml () const;
 
 	/** Emitted with a parameter between 0 and 1 to indicate progress
@@ -62,12 +124,35 @@ public:
 
 private:
 
-	std::string write_cpl (std::string) const;
-	std::string write_pkl (std::string, std::string, std::string, int) const;
+	/** Write the CPL file.
+	 *  @param cpl_uuid UUID to use.
+	 *  @return CPL pathname.
+	 */
+	std::string write_cpl (std::string cpl_uuid) const;
+
+	/** Write the PKL file.
+	 *  @param pkl_uuid UUID to use.
+	 *  @param cpl_uuid UUID of the CPL file.
+	 *  @param cpl_digest SHA digest of the CPL file.
+	 *  @param cpl_length Length of the CPL file in bytes.
+	 */
+	std::string write_pkl (std::string pkl_uuid, std::string cpl_uuid, std::string cpl_digest, int cpl_length) const;
+	
+	/** Write the VOLINDEX file */
 	void write_volindex () const;
-	void write_assetmap (std::string, int, std::string, int) const;
 
-	static std::string content_type_string (ContentType);
+	/** Write the ASSETMAP file.
+	 *  @param cpl_uuid UUID of our CPL.
+	 *  @param cpl_length Length of our CPL in bytes.
+	 *  @param pkl_uuid UUID of our PKL.
+	 *  @param pkl_length Length of our PKL in bytes.
+	 */
+	void write_assetmap (std::string cpl_uuid, int cpl_length, std::string pkl_uuid, int pkl_length) const;
+
+	/** @param type A content type.
+	 *  @return A string representation suitable for use in a CPL.
+	 */
+	static std::string content_type_string (ContentType type);
 
 	/** the directory that we are writing to */
 	std::string _directory;
diff --git a/src/picture_asset.cc b/src/picture_asset.cc
index c989539b..8ddaea84 100644
--- a/src/picture_asset.cc
+++ b/src/picture_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/picture_asset.h
+ *  @brief An asset made up of JPEG2000 files
+ */
+
 #include <list>
 #include <stdexcept>
 #include <iostream>
@@ -31,20 +35,17 @@ using namespace std;
 using namespace boost;
 using namespace libdcp;
 
-/** Construct a PictureAsset, generating the MXF from the JPEG2000 files.
- *  This may take some time; progress is indicated by emission of the Progress signal.
- *  @param files Pathnames of JPEG2000 files, in frame order.
- *  @param p Pathname of MXF file to create.
- *  @param fps Frames per second.
- *  @param len Length in frames.
- *  @param w Width of images in pixels.
- *  @param h Height of images in pixels.
- */
-
-PictureAsset::PictureAsset (list<string> const & files, string p, sigc::signal1<void, float>* progress, int fps, int len, int w, int h)
-	: Asset (p, progress, fps, len)
-	, _width (w)
-	, _height (h)
+PictureAsset::PictureAsset (
+	list<string> const & files,
+	string mxf_path,
+	sigc::signal1<void, float>* progress,
+	int fps,
+	int length,
+	int width,
+	int height)
+	: Asset (mxf_path, progress, fps, length)
+	, _width (width)
+	, _height (height)
 {
 	ASDCP::JP2K::CodestreamParser j2k_parser;
 	ASDCP::JP2K::FrameBuffer frame_buffer (4 * Kumu::Megabyte);
@@ -90,9 +91,6 @@ PictureAsset::PictureAsset (list<string> const & files, string p, sigc::signal1<
 	_digest = make_digest (_mxf_path, _progress);
 }
 
-/** Write details of this asset to a CPL stream.
- *  @param s Stream.
- */
 void
 PictureAsset::write_to_cpl (ostream& s) const
 {
diff --git a/src/picture_asset.h b/src/picture_asset.h
index 3027a789..2f3c7cdf 100644
--- a/src/picture_asset.h
+++ b/src/picture_asset.h
@@ -17,18 +17,43 @@
 
 */
 
+/** @file  src/picture_asset.h
+ *  @brief An asset made up of JPEG2000 files
+ */
+
 #include "asset.h"
 
 namespace libdcp
 {
 
-/** An asset made up of JPEG2000 files */
+/** @brief An asset made up of JPEG2000 files */
 class PictureAsset : public Asset
 {
 public:
-	PictureAsset (std::list<std::string> const &, std::string, sigc::signal1<void, float>*, int, int, int, int);
+	/** Construct a PictureAsset, generating the MXF from the JPEG2000 files.
+	 *  This may take some time; progress is indicated by emission of the Progress signal.
+	 *  @param files Pathnames of JPEG2000 files, in frame order.
+	 *  @param mxf_path Pathname of MXF file to create.
+	 *  @param progress Signal to inform of progress.
+	 *  @param fps Frames per second.
+	 *  @param length Length in frames.
+	 *  @param width Width of images in pixels.
+	 *  @param height Height of images in pixels.
+	 */
+	PictureAsset (
+		std::list<std::string> const & files,
+		std::string mxf_path,
+		sigc::signal1<void, float>* progress,
+		int fps,
+		int length,
+		int width,
+		int height
+		);
 
-	void write_to_cpl (std::ostream &) const;
+	/** Write details of this asset to a CPL stream.
+	 *  @param s Stream.
+	 */
+	void write_to_cpl (std::ostream& s) const;
 
 private:
 	/** picture width in pixels */
diff --git a/src/sound_asset.cc b/src/sound_asset.cc
index 50bf463c..8c85f9df 100644
--- a/src/sound_asset.cc
+++ b/src/sound_asset.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/sound_asset.cc
+ *  @brief An asset made up of WAV files
+ */
+
 #include <iostream>
 #include <stdexcept>
 #include <boost/filesystem.hpp>
@@ -28,16 +32,8 @@ using namespace std;
 using namespace boost;
 using namespace libdcp;
 
-/** Construct a SoundAsset, generating the MXF from the WAV files.
- *  This may take some time; progress is indicated by emission of the Progress signal.
- *  @param files Pathnames of sound files, in the order Left, Right, Centre, Lfe (sub), Left surround, Right surround.
- *  @param p Pathname of MXF file to create.
- *  @param fps Frames per second.
- *  @param len Length in frames.
- */
-
-SoundAsset::SoundAsset (list<string> const & files, string p, sigc::signal1<void, float>* progress, int fps, int len)
-	: Asset (p, progress, fps, len)
+SoundAsset::SoundAsset (list<string> const & files, string mxf_path, sigc::signal1<void, float>* progress, int fps, int length)
+	: Asset (mxf_path, progress, fps, length)
 {
 	ASDCP::Rational asdcp_fps (_fps, 1);
 	
@@ -124,10 +120,6 @@ SoundAsset::SoundAsset (list<string> const & files, string p, sigc::signal1<void
 	_digest = make_digest (_mxf_path, _progress);
 }
 
-/** Write details of this asset to a CPL stream.
- *  @param s Stream.
- */
-
 void
 SoundAsset::write_to_cpl (ostream& s) const
 {
diff --git a/src/sound_asset.h b/src/sound_asset.h
index aa1362f6..c63bab90 100644
--- a/src/sound_asset.h
+++ b/src/sound_asset.h
@@ -17,18 +17,33 @@
 
 */
 
+/** @file  src/sound_asset.h
+ *  @brief An asset made up of WAV files
+ */
+
 #include "asset.h"
 
 namespace libdcp
 {
 
-/** An asset made up of WAV files */
+/** @brief An asset made up of WAV files */
 class SoundAsset : public Asset
 {
 public:
-	SoundAsset (std::list<std::string> const &, std::string, sigc::signal1<void, float>*, int, int);
-
-	void write_to_cpl (std::ostream &) const;
+	/** Construct a SoundAsset, generating the MXF from the WAV files.
+	 *  This may take some time; progress is indicated by emission of the Progress signal.
+	 *  @param files Pathnames of sound files, in the order Left, Right, Centre, Lfe (sub), Left surround, Right surround.
+	 *  @param mxf_path Pathname of MXF file to create.
+	 *  @param progress Signal to inform of progress.
+	 *  @param fps Frames per second.
+	 *  @param length Length in frames.
+	 */
+	SoundAsset (std::list<std::string> const & files, std::string mxf_path, sigc::signal1<void, float>* progress, int fps, int length);
+
+	/** Write details of this asset to a CPL stream.
+	 *  @param s Stream.
+	 */
+	void write_to_cpl (std::ostream& s) const;
 };
 
 }
diff --git a/src/util.cc b/src/util.cc
index 0af9c871..2968ef55 100644
--- a/src/util.cc
+++ b/src/util.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/util.cc
+ *  @brief Utility methods.
+ */
+
 #include <stdexcept>
 #include <sstream>
 #include <iostream>
@@ -31,9 +35,6 @@
 using namespace std;
 using namespace boost;
 
-/** Create a UUID.
- *  @return UUID.
- */
 string
 libdcp::make_uuid ()
 {
@@ -44,10 +45,6 @@ libdcp::make_uuid ()
 	return string (buffer);
 }
 
-/** Create a digest for a file.
- *  @param filename File name.
- *  @return Digest.
- */
 string
 libdcp::make_digest (string filename, sigc::signal1<void, float>* progress)
 {
diff --git a/src/util.h b/src/util.h
index 9ed674f7..e4034da2 100644
--- a/src/util.h
+++ b/src/util.h
@@ -21,8 +21,18 @@
 #include <sigc++/sigc++.h>
 
 namespace libdcp {
-	
+
+/** Create a UUID.
+ *  @return UUID.
+ */
 extern std::string make_uuid ();
-extern std::string make_digest (std::string, sigc::signal1<void, float> *);
+
+/** Create a digest for a file.
+ *  @param filename File name.
+ *  @param progress If non-0, a signal which will be emitted periodically to update
+ *  progress; the parameter will start at 0.5 and proceed to 1.
+ *  @return Digest.
+ */
+extern std::string make_digest (std::string filename, sigc::signal1<void, float>* progress);
 
 }