A little tidying up.

13 files changed, 94 insertions, 41 deletions

diff --git a/src/asset.h b/src/asset.h
index e8867ae5..abaa63be 100644
--- a/src/asset.h
+++ b/src/asset.h
@@ -39,7 +39,7 @@ namespace dcp {
  *  @brief Parent class for DCP assets, i.e. picture/sound/subtitles and CPLs.
  *
  *  Note that this class is not used for ReelAssets; they are just for the metadata
- *  that gets put into <Reel>s.
+ *  that gets put into &lt;Reel&gt;s.
  */
 class Asset : public Object
 {
diff --git a/src/certificates.cc b/src/certificates.cc
index 222352f2..0a0393c6 100644
--- a/src/certificates.cc
+++ b/src/certificates.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/certificates.cc
+ *  @brief Certificate and CertificateChain classes.
+ */
+
 #include "KM_util.h"
 #include "certificates.h"
 #include "compose.hpp"
@@ -160,7 +164,7 @@ Certificate::certificate (bool with_begin_end) const
 }
 
 /** @return Certificate's issuer, in the form
- *  dnqualifier=<dnQualififer>,CN=<commonName>,OU=<organizationalUnitName>,O=organizationName
+ *  dnqualifier=&lt;dnQualififer&gt;,CN=&lt;commonName&gt;,OU=&lt;organizationalUnitName&gt,O=&lt;organizationName&gt;
  *  and with + signs escaped to \+
  */
 string
diff --git a/src/dcp.cc b/src/dcp.cc
index 808c040e..dc67dd2e 100644
--- a/src/dcp.cc
+++ b/src/dcp.cc
@@ -52,8 +52,6 @@ using std::string;
 using std::list;
 using std::stringstream;
 using std::ostream;
-using std::copy;
-using std::back_inserter;
 using std::make_pair;
 using std::map;
 using boost::shared_ptr;
diff --git a/src/dcp.h b/src/dcp.h
index 9f6d60fd..3f4c8418 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -18,7 +18,7 @@
 */
 
 /** @file  src/dcp.h
- *  @brief A class to create or read a DCP.
+ *  @brief DCP class.
  */
 
 #ifndef LIBDCP_DCP_H
@@ -73,6 +73,7 @@ public:
 	/** Compare this DCP with another, according to various options.
 	 *  @param other DCP to compare this one to.
 	 *  @param options Options to define what "equality" means.
+	 *  @param note Functor to handle notes made by the equality operation.
 	 *  @return true if the DCPs are equal according to EqualityOptions, otherwise false.
 	 */
 	bool equals (DCP const & other, EqualityOptions options, boost::function<void (NoteType, std::string)> note) const;
@@ -113,6 +114,7 @@ private:
 
 	/** the directory that we are writing to */
 	boost::filesystem::path _directory;
+	/** the assets that make up this DCP */
 	std::list<boost::shared_ptr<Asset> > _assets;
 };
 
diff --git a/src/kdm.h b/src/kdm.h
index 9ee793c9..567ff844 100644
--- a/src/kdm.h
+++ b/src/kdm.h
@@ -161,8 +161,8 @@ public:
 	 *  @param recipient_cert Certificate of the projector that this KDM is targeted at.
 	 *  @param not_valid_before Start of validity period.
 	 *  @param not_valid_after End of validity period.
-	 *  @param annotation_text Text for the <AnnotationText> node.
-	 *  @param issue_date Text for the <IssueDate> node.
+	 *  @param annotation_text Text for the &lt;AnnotationText&gt; node.
+	 *  @param issue_date Text for the &lt;IssueDate&gt; node.
 	 */
 	KDM (
 		boost::shared_ptr<const CPL> cpl, boost::shared_ptr<const Signer> signer, boost::shared_ptr<const Certificate> recipient_cert,
diff --git a/src/mono_picture_frame.cc b/src/mono_picture_frame.cc
index 964b543b..9fa13d88 100644
--- a/src/mono_picture_frame.cc
+++ b/src/mono_picture_frame.cc
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -17,9 +17,10 @@
 
 */
 
-#include <openjpeg.h>
-#include "AS_DCP.h"
-#include "KM_fileio.h"
+/** @file  src/mono_picture_frame.cc
+ *  @brief MonoPictureFrame class.
+ */
+
 #include "mono_picture_frame.h"
 #include "exceptions.h"
 #include "argb_frame.h"
@@ -27,6 +28,9 @@
 #include "util.h"
 #include "gamma_lut.h"
 #include "rgb_xyz.h"
+#include "KM_fileio.h"
+#include "AS_DCP.h"
+#include <openjpeg.h>
 
 #define DCI_GAMMA 2.6
 
@@ -37,6 +41,7 @@ using namespace dcp;
 /** Make a picture frame from a 2D (monoscopic) asset.
  *  @param mxf_path Path to the asset's MXF file.
  *  @param n Frame within the asset, not taking EntryPoint into account.
+ *  @param c Context for decryption, or 0.
  */
 MonoPictureFrame::MonoPictureFrame (boost::filesystem::path mxf_path, int n, ASDCP::AESDecContext* c)
 {
@@ -54,17 +59,20 @@ MonoPictureFrame::MonoPictureFrame (boost::filesystem::path mxf_path, int n, ASD
 	}
 }
 
+/** MonoPictureFrame destructor */
 MonoPictureFrame::~MonoPictureFrame ()
 {
 	delete _buffer;
 }
 
+/** @return Pointer to JPEG2000 data */
 uint8_t const *
 MonoPictureFrame::j2k_data () const
 {
 	return _buffer->RoData ();
 }
 
+/** @return Size of JPEG2000 data in bytes */
 int
 MonoPictureFrame::j2k_size () const
 {
@@ -74,11 +82,12 @@ MonoPictureFrame::j2k_size () const
 /** @param reduce a factor by which to reduce the resolution
  *  of the image, expressed as a power of two (pass 0 for no
  *  reduction).
+ *  @param srgb_gamma Reciprocal of output gamma to use after
+ *  the conversion from XYZ to RGB.
  *
  *  @return An ARGB representation of this frame.  This is ARGB in the
  *  Cairo sense, so that each pixel takes up 4 bytes; the first byte
  *  is blue, second green, third red and fourth alpha (always 255).
- *
  */
 shared_ptr<ARGBFrame>
 MonoPictureFrame::argb_frame (int reduce, float srgb_gamma) const
diff --git a/src/mono_picture_frame.h b/src/mono_picture_frame.h
index 44df68c9..cc6096cd 100644
--- a/src/mono_picture_frame.h
+++ b/src/mono_picture_frame.h
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012-2013 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -17,10 +17,16 @@
 
 */
 
+/** @file  src/mono_picture_frame.h
+ *  @brief MonoPictureFrame class.
+ */
+
+#include "types.h"
+#include <boost/shared_ptr.hpp>
+#include <boost/noncopyable.hpp>
+#include <boost/filesystem.hpp>
 #include <string>
 #include <stdint.h>
-#include <boost/shared_ptr.hpp>
-#include "types.h"
 
 namespace ASDCP {
 	namespace JP2K {
@@ -33,8 +39,10 @@ namespace dcp {
 
 class ARGBFrame;
 
-/** A single frame of a 2D (monoscopic) picture asset */	
-class MonoPictureFrame
+/** @class MonoPictureFrame
+ *  @brief A single frame of a 2D (monoscopic) picture asset.
+ */
+class MonoPictureFrame : public boost::noncopyable
 {
 public:
 	MonoPictureFrame (boost::filesystem::path mxf_path, int n, ASDCP::AESDecContext *);
diff --git a/src/object.cc b/src/object.cc
index e3849d79..315e501a 100644
--- a/src/object.cc
+++ b/src/object.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/object.cc
+ *  @brief Object class.
+ */
+
 #include "object.h"
 #include "util.h"
 
@@ -31,7 +35,7 @@ Object::Object ()
 }
 
 /** Create an Object with a given ID.
- *  @param ID to use.
+ *  @param id ID to use.
  */
 Object::Object (string id)
 	: _id (id)
diff --git a/src/object.h b/src/object.h
index e12888e8..1b99e363 100644
--- a/src/object.h
+++ b/src/object.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/object.h
+ *  @brief Object class.
+ */
+
 #ifndef LIBDCP_OBJECT_H
 #define LIBDCP_OBJECT_H
 
diff --git a/src/signer.cc b/src/signer.cc
index 4c5d199a..a280cb07 100644
--- a/src/signer.cc
+++ b/src/signer.cc
@@ -38,7 +38,7 @@ using namespace dcp;
 
 /** Add a &lt;Signer&gt; and &lt;ds:Signature&gt; nodes to an XML node.
  *  @param parent XML node to add to.
- *  @param interop true to use Interop standards, false for SMPTE.
+ *  @param standard INTEROP or SMPTE.
  */
 void
 Signer::sign (xmlpp::Element* parent, Standard standard) const
diff --git a/src/util.cc b/src/util.cc
index fe89ca72..767c1490 100644
--- a/src/util.cc
+++ b/src/util.cc
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -121,7 +121,7 @@ dcp::make_digest (boost::filesystem::path filename, boost::function<void (float)
 }
 
 /** Convert a content kind to a string which can be used in a
- *  <ContentKind> node.
+ *  &lt;ContentKind&gt; node.
  *  @param kind ContentKind.
  *  @return string.
  */
@@ -154,7 +154,7 @@ dcp::content_kind_to_string (ContentKind kind)
 	assert (false);
 }
 
-/** Convert a string from a <ContentKind> node to a libdcp ContentKind.
+/** Convert a string from a &lt;ContentKind&gt; node to a libdcp ContentKind.
  *  Reasonably tolerant about varying case.
  *  @param type Content kind string.
  *  @return libdcp ContentKind.
@@ -237,6 +237,9 @@ dcp::empty_or_white_space (string s)
 	return true;
 }
 
+/** Set up various bits that the library needs.  Should be called one
+ *  by client applications.
+ */
 void
 dcp::init ()
 {
@@ -269,8 +272,14 @@ bool dcp::operator!= (dcp::Size const & a, dcp::Size const & b)
 	return !(a == b);
 }
 
-/** The base64 decode routine in KM_util.cpp gives different values to both
- *  this and the command-line base64 for some inputs.  Not sure why.
+/** Decode a base64 string.  The base64 decode routine in KM_util.cpp
+ *  gives different values to both this and the command-line base64
+ *  for some inputs.  Not sure why.
+ *
+ *  @param in base64-encoded string.
+ *  @param out Output buffer.
+ *  @param out_length Length of output buffer.
+ *  @return Number of characters written to the output buffer.
  */
 int
 dcp::base64_decode (string const & in, unsigned char* out, int out_length)
@@ -297,6 +306,11 @@ dcp::base64_decode (string const & in, unsigned char* out, int out_length)
 	return N;
 }
 
+/** Convert a struct tm to a string of the form
+ *  2014-01-26T21:39:00+01:00
+ *  @param tm struct tm.
+ *  @return Time as a string.
+ */
 string
 dcp::tm_to_string (struct tm* tm)
 {
@@ -339,6 +353,11 @@ dcp::utc_offset_to_string (int b)
 	return o.str ();
 }
 
+/** Convert a boost::posix_time::ptime to a string of the form
+ *  2014-01-26T21:39:00+01:00.
+ *  @param t boost::posix_time::ptime.
+ *  @return Time as a string.
+ */
 string
 dcp::ptime_to_string (boost::posix_time::ptime t)
 {
@@ -347,10 +366,14 @@ dcp::ptime_to_string (boost::posix_time::ptime t)
 }
 
 
-/* Apparently there is no way to create an ofstream using a UTF-8
-   filename under Windows.  We are hence reduced to using fopen
-   with this wrapper.
-*/
+/** @param p Path to open.
+ *  @param t mode flags, as for fopen(3).
+ *  @return FILE pointer or 0 on error.
+ *
+ *  Apparently there is no way to create an ofstream using a UTF-8
+ *  filename under Windows.  We are hence reduced to using fopen
+ *  with this wrapper.
+ */
 FILE *
 dcp::fopen_boost (boost::filesystem::path p, string t)
 {
diff --git a/src/util.h b/src/util.h
index 5d7a9c4f..e26c7332 100644
--- a/src/util.h
+++ b/src/util.h
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -24,14 +24,14 @@
  *  @brief Utility methods.
  */
 
-#include <string>
-#include <stdint.h>
+#include "types.h"
 #include <boost/shared_ptr.hpp>
 #include <boost/function.hpp>
 #include <boost/date_time/posix_time/posix_time.hpp>
 #include <boost/filesystem.hpp>
 #include <openjpeg.h>
-#include "types.h"
+#include <string>
+#include <stdint.h>
 
 namespace xmlpp {
 	class Element;
@@ -44,7 +44,8 @@ class CertificateChain;
 class GammaLUT;
 class XYZFrame;
 
-struct Size {
+struct Size
+{
 	Size ()
 		: width (0)
 		, height (0)
diff --git a/src/xml/kdm_smpte.h b/src/xml/kdm_smpte.h
index 49281d70..7154958a 100644
--- a/src/xml/kdm_smpte.h
+++ b/src/xml/kdm_smpte.h
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2013 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2013-2014 Carl Hetherington <cth@carlh.net>
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -32,14 +32,14 @@
 #ifndef LIBDCP_XML_KDM_SMPTE_H
 #define LIBDCP_XML_KDM_SMPTE_H
 
-#include <string>
-#include <list>
-#include <boost/optional.hpp>
-#include <boost/filesystem.hpp>
+#include "../exceptions.h"
+#include <libcxml/cxml.h>
 #include <libxml/parser.h>
 #include <libxml++/libxml++.h>
-#include <libcxml/cxml.h>
-#include "../exceptions.h"
+#include <boost/optional.hpp>
+#include <boost/filesystem.hpp>
+#include <string>
+#include <list>
 
 namespace dcp {
 namespace xml {