Comments / tidying up.

9 files changed, 72 insertions, 38 deletions

diff --git a/src/certificates.h b/src/certificates.h
index 8ec5ddd5..8cb570c0 100644
--- a/src/certificates.h
+++ b/src/certificates.h
@@ -89,7 +89,7 @@ class CertificateChain
 public:
 	CertificateChain () {}
 
-	void add (boost::shared_ptr<Certificate>);
+	void add (boost::shared_ptr<Certificate> c);
 
 	boost::shared_ptr<Certificate> root () const;
 	boost::shared_ptr<Certificate> leaf () const;
diff --git a/src/cpl.cc b/src/cpl.cc
index 0cd1d6ce..a27e8fda 100644
--- a/src/cpl.cc
+++ b/src/cpl.cc
@@ -83,6 +83,9 @@ CPL::CPL (boost::filesystem::path file)
 	f.done ();
 }
 
+/** Add a reel to this CPL.
+ *  @param reel Reel to add.
+ */
 void
 CPL::add (shared_ptr<Reel> reel)
 {
diff --git a/src/kdm.cc b/src/kdm.cc
index 92e9a756..dc326556 100644
--- a/src/kdm.cc
+++ b/src/kdm.cc
@@ -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
@@ -17,15 +17,10 @@
 
 */
 
-#include <iomanip>
-#include <algorithm>
-#include <boost/algorithm/string.hpp>
-#include <openssl/rsa.h>
-#include <openssl/pem.h>
-#include <openssl/err.h>
-#include <libcxml/cxml.h>
-#include "AS_DCP.h"
-#include "KM_util.h"
+/** @file  src/kdm.cc
+ *  @brief KDM and KDMKey classes.
+ */
+
 #include "util.h"
 #include "kdm.h"
 #include "compose.hpp"
@@ -34,6 +29,15 @@
 #include "cpl.h"
 #include "mxf.h"
 #include "xml/kdm_smpte.h"
+#include "AS_DCP.h"
+#include "KM_util.h"
+#include <libcxml/cxml.h>
+#include <openssl/rsa.h>
+#include <openssl/pem.h>
+#include <openssl/err.h>
+#include <boost/algorithm/string.hpp>
+#include <iomanip>
+#include <algorithm>
 
 using std::list;
 using std::string;
diff --git a/src/kdm.h b/src/kdm.h
index 567ff844..f6d96b39 100644
--- a/src/kdm.h
+++ b/src/kdm.h
@@ -18,7 +18,7 @@
 */
 
 /** @file  src/kdm.h
- *  @brief Handling of Key Delivery Messages (KDMs).
+ *  @brief KDM and KDMKey classes.
  */
 
 #ifndef LIBDCP_KDM_H
diff --git a/src/signer_chain.cc b/src/signer_chain.cc
index 5f9941f9..87bacc53 100644
--- a/src/signer_chain.cc
+++ b/src/signer_chain.cc
@@ -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
@@ -17,17 +17,21 @@
 
 */
 
-#include <fstream>
-#include <sstream>
-#include <boost/filesystem.hpp>
-#include <boost/algorithm/string.hpp>
-#include <openssl/sha.h>
-#include <openssl/bio.h>
-#include <openssl/evp.h>
-#include "KM_util.h"
+/** @file  src/signer_chain.cc
+ *  @brief Functions to make signer chains.
+ */
+
 #include "signer_chain.h"
 #include "exceptions.h"
 #include "util.h"
+#include "KM_util.h"
+#include <openssl/sha.h>
+#include <openssl/bio.h>
+#include <openssl/evp.h>
+#include <boost/filesystem.hpp>
+#include <boost/algorithm/string.hpp>
+#include <fstream>
+#include <sstream>
 
 using std::string;
 using std::ofstream;
@@ -35,7 +39,11 @@ using std::ifstream;
 using std::stringstream;
 using std::cout;
 
-static void command (string cmd)
+/** Run a shell command.
+ *  @param cmd Command to run (UTF8-encoded).
+ */
+static void
+command (string cmd)
 {
 #ifdef LIBDCP_WINDOWS
 	/* We need to use CreateProcessW on Windows so that the UTF-8/16 mess
@@ -81,11 +89,10 @@ static void command (string cmd)
 }
 
 /** Extract a public key from a private key and create a SHA1 digest of it.
- *  @param key Private key
+ *  @param private_key Private key
  *  @param openssl openssl binary name (or full path if openssl is not on the system path).
  *  @return SHA1 digest of corresponding public key, with escaped / characters.
  */
-	
 static string
 public_key_digest (boost::filesystem::path private_key, boost::filesystem::path openssl)
 {
@@ -148,6 +155,10 @@ public_key_digest (boost::filesystem::path private_key, boost::filesystem::path
 	return dig;
 }
 
+/** Generate a chain of root, intermediate and leaf keys by running an OpenSSL binary.
+ *  @param directory Directory to write the files to.
+ *  @param openssl openssl binary path.
+ */
 void
 dcp::make_signer_chain (boost::filesystem::path directory, boost::filesystem::path openssl)
 {
diff --git a/src/signer_chain.h b/src/signer_chain.h
index 034e2290..f039caf3 100644
--- a/src/signer_chain.h
+++ b/src/signer_chain.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
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/signer_chain.h
+ *  @brief Functions to make signer chains.
+ */
+
 #include <boost/filesystem.hpp>
 
 namespace dcp {
diff --git a/src/text.cc b/src/text.cc
index 5d2a2d1b..c70e4333 100644
--- a/src/text.cc
+++ b/src/text.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/text.cc
+ *  @brief Text class for parsing subtitle XML.
+ */
+
 #include "text.h"
 #include "xml.h"
 #include "font.h"
@@ -27,6 +31,10 @@ using boost::shared_ptr;
 using boost::optional;
 using namespace dcp;
 
+/** Read a &lt;Text&gt; node from a subtitle XML file, noting its contents
+ *  in this object's member variables.
+ *  @param node Node to read.
+ */
 Text::Text (shared_ptr<const cxml::Node> node)
 	: v_align (CENTER)
 {
diff --git a/src/text.h b/src/text.h
index 81992d6f..bbb99adb 100644
--- a/src/text.h
+++ b/src/text.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/text.h
+ *  @brief Text class for parsing subtitle XML.
+ */
+
 #include "types.h"
 #include <boost/shared_ptr.hpp>
 #include <list>
diff --git a/src/util.cc b/src/util.cc
index 767c1490..e53556e4 100644
--- a/src/util.cc
+++ b/src/util.cc
@@ -156,33 +156,33 @@ dcp::content_kind_to_string (ContentKind kind)
 
 /** Convert a string from a &lt;ContentKind&gt; node to a libdcp ContentKind.
  *  Reasonably tolerant about varying case.
- *  @param type Content kind string.
+ *  @param kind Content kind string.
  *  @return libdcp ContentKind.
  */
 dcp::ContentKind
-dcp::content_kind_from_string (string type)
+dcp::content_kind_from_string (string kind)
 {
-	transform (type.begin(), type.end(), type.begin(), ::tolower);
+	transform (kind.begin(), kind.end(), kind.begin(), ::tolower);
 	
-	if (type == "feature") {
+	if (kind == "feature") {
 		return FEATURE;
-	} else if (type == "short") {
+	} else if (kind == "short") {
 		return SHORT;
-	} else if (type == "trailer") {
+	} else if (kind == "trailer") {
 		return TRAILER;
-	} else if (type == "test") {
+	} else if (kind == "test") {
 		return TEST;
-	} else if (type == "transitional") {
+	} else if (kind == "transitional") {
 		return TRANSITIONAL;
-	} else if (type == "rating") {
+	} else if (kind == "rating") {
 		return RATING;
-	} else if (type == "teaser") {
+	} else if (kind == "teaser") {
 		return TEASER;
-	} else if (type == "policy") {
+	} else if (kind == "policy") {
 		return POLICY;
-	} else if (type == "psa") {
+	} else if (kind == "psa") {
 		return PUBLIC_SERVICE_ANNOUNCEMENT;
-	} else if (type == "advertisement") {
+	} else if (kind == "advertisement") {
 		return ADVERTISEMENT;
 	}