Doc tweaks.

8 files changed, 115 insertions, 46 deletions

diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index 2ebabc02..9d7139fa 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -7,10 +7,83 @@ libdcp is a small library to create Digital Cinema Packages (DCPs) from JPEG2000
 Most of the hard work is done by a (slightly patched) version of asdcplib (http://www.cinecert.com/asdcplib/)
 which is included in the source distribution for libdcp.
 
-See libdcp::DCP for an example of libdcp's use.
-
 libdcp is distributed under the GNU GPL.
 
+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);
+
+vector<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);
+
+vector<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%).
+
+If you can generate content paths algorithmically, you may prefer to do something
+like this:
+
+@code
+
+string
+j2k_path (int frame)
+{
+	stringstream s;
+	s << "my_j2ks/" << frame << ".j2c"
+	return s.str ();
+}
+
+string
+wav_path (libdcp::Channel channel)
+{
+	switch (channel) {
+	case LEFT:
+		return "left.wav";
+	case RIGHT:
+		return "right.wav";
+	}
+
+	return "";
+}
+
+...
+
+// Our images are 1998x1080 (DCI Flat)
+dcp.add_picture_asset (sigc::ptr_fun (&j2k_path), 1998, 1080);
+// We have two sound channels
+dcp.add_sound_asset (sigc::ptr_fun (&wav_path), 2);
+
+...
+
+@endcode
+
 */
 
 
diff --git a/src/dcp.cc b/src/dcp.cc
index c466396c..27ae9636 100644
--- a/src/dcp.cc
+++ b/src/dcp.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/dcp.cc
+ *  @brief A class to create a DCP.
+ */
+
 #include <sstream>
 #include <fstream>
 #include <iomanip>
diff --git a/src/dcp.h b/src/dcp.h
index f683c419..9bd5f3ea 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/dcp.h
+ *  @brief A class to create a DCP.
+ */
+
 #ifndef LIBDCP_DCP_H
 #define LIBDCP_DCP_H
 
@@ -34,46 +38,8 @@ class Asset;
 
 /** @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);
- *
- *  vector<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);
- *
- *  vector<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:
diff --git a/src/exceptions.h b/src/exceptions.h
index 0dbbec4b..7443db15 100644
--- a/src/exceptions.h
+++ b/src/exceptions.h
@@ -24,6 +24,7 @@
 namespace libdcp
 {
 
+/** @brief An exception related to a file */
 class FileError : public std::exception
 {
 public:
@@ -34,30 +35,38 @@ public:
 			    
 	~FileError () throw () {}
 
+	/** @return error message */
 	char const * what () const throw () {
 		return _message.c_str ();
 	}
 	
+	/** @return filename of file that was involved */
 	std::string filename () const {
 		return _filename;
 	}
 
 private:
+	/** error message */
 	std::string _message;
+	/** filename of file that was involved */
 	std::string _filename;
 };
 
+
+/** @brief A miscellaneous exception */
 class MiscError : public std::exception
 {
 public:
 	MiscError (std::string const & message) : _message (message) {}
 	~MiscError () throw () {}
 
+	/** @return error message */
 	char const * what () const throw () {
 		return _message.c_str ();
 	}
 
 private:
+	/** error message */
 	std::string _message;
 };
 
diff --git a/src/metadata.cc b/src/metadata.cc
index 797d645d..07e289b3 100644
--- a/src/metadata.cc
+++ b/src/metadata.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/metadata.cc
+ *  @brief Metadata for writing to the DCP.
+ */
+
 #include "metadata.h"
 
 using namespace std;
diff --git a/src/metadata.h b/src/metadata.h
index 7660c4dd..1610491e 100644
--- a/src/metadata.h
+++ b/src/metadata.h
@@ -17,14 +17,19 @@
 
 */
 
+/** @file  src/metadata.h
+ *  @brief Metadata for writing to the DCP.
+ */
+
 #include <string>
 
 namespace libdcp
 {
 
-/** A class to hold various metadata that will be written
- *  to the DCP.  The values are initialised, and can be modified
- *  if desired.
+/** @brief A class to hold various metadata that will be written
+ *  to the DCP.
+ *
+ *  The values are initialised, and can be modified if desired.
  */
 class Metadata
 {
diff --git a/src/types.h b/src/types.h
index 286c3623..e2b91670 100644
--- a/src/types.h
+++ b/src/types.h
@@ -17,8 +17,12 @@
 
 */
 
-#ifndef LIBDCP_CHANNEL_H
-#define LIBDCP_CHANNEL_H
+/** @file  src/types.h
+ *  @brief Miscellaneous types.
+ */
+
+#ifndef LIBDCP_TYPES_H
+#define LIBDCP_TYPES_H
 
 namespace libdcp
 {
diff --git a/src/util.h b/src/util.h
index e4034da2..b6c945a5 100644
--- a/src/util.h
+++ b/src/util.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/util.h
+ *  @brief Utility methods.
+ */
+
 #include <string>
 #include <sigc++/sigc++.h>