Comments.

15 files changed, 115 insertions, 32 deletions

diff --git a/src/lib/content_factory.cc b/src/lib/content_factory.cc
index 092efd790..789496d08 100644
--- a/src/lib/content_factory.cc
+++ b/src/lib/content_factory.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,6 +17,10 @@
 
 */
 
+/** @file  src/lib/content_factory.cc
+ *  @brief Methods to create content objects.
+ */
+
 #include <libcxml/cxml.h>
 #include "ffmpeg_content.h"
 #include "image_content.h"
@@ -28,6 +32,13 @@ using std::string;
 using std::list;
 using boost::shared_ptr;
 
+/** Create a Content object from an XML node.
+ *  @param film Film that the content will be in.
+ *  @param node XML description.
+ *  @param version XML state version.
+ *  @param notes A list to which is added descriptions of any non-critial warnings / messages.
+ *  @return Content object, or 0 if no content was recognised in the XML.
+ */
 shared_ptr<Content>
 content_factory (shared_ptr<const Film> film, cxml::NodePtr node, int version, list<string>& notes)
 {
@@ -48,6 +59,11 @@ content_factory (shared_ptr<const Film> film, cxml::NodePtr node, int version, l
 	return content;
 }
 
+/** Create a Content object from a file, depending on its extension.
+ *  @param film Film that the content will be in.
+ *  @param path File's path.
+ *  @return Content object.
+ */
 shared_ptr<Content>
 content_factory (shared_ptr<const Film> film, boost::filesystem::path path)
 {
diff --git a/src/lib/content_factory.h b/src/lib/content_factory.h
index 2eeebbc9f..fae7648ea 100644
--- a/src/lib/content_factory.h
+++ b/src/lib/content_factory.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/lib/content_factory.h
+ *  @brief Methods to create content objects.
+ */
+
 class Film;
 
 extern boost::shared_ptr<Content> content_factory (boost::shared_ptr<const Film>, cxml::NodePtr, int, std::list<std::string> &);
diff --git a/src/lib/decoder.h b/src/lib/decoder.h
index 38556c818..0ec73ba91 100644
--- a/src/lib/decoder.h
+++ b/src/lib/decoder.h
@@ -18,7 +18,7 @@
 */
 
 /** @file  src/decoder.h
- *  @brief Parent class for decoders of content.
+ *  @brief Decoder class.
  */
 
 #ifndef DCPOMATIC_DECODER_H
diff --git a/src/lib/exceptions.cc b/src/lib/exceptions.cc
index e05ac4ff0..4d9ccc95c 100644
--- a/src/lib/exceptions.cc
+++ b/src/lib/exceptions.cc
@@ -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
diff --git a/src/lib/exceptions.h b/src/lib/exceptions.h
index 213be6186..38452ffc0 100644
--- a/src/lib/exceptions.h
+++ b/src/lib/exceptions.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
@@ -17,13 +17,13 @@
 
 */
 
-#ifndef DCPOMATIC_EXCEPTIONS_H
-#define DCPOMATIC_EXCEPTIONS_H
-
-/** @file  src/exceptions.h
+/** @file  src/lib/exceptions.h
  *  @brief Our exceptions.
  */
 
+#ifndef DCPOMATIC_EXCEPTIONS_H
+#define DCPOMATIC_EXCEPTIONS_H
+
 #include <stdexcept>
 #include <cstring>
 #include <boost/exception/all.hpp>
@@ -205,7 +205,7 @@ public:
 	{}
 };
 
-/** @class NetworkError.
+/** @class NetworkError
  *  @brief Indicates some problem with communication on the network.
  */
 class NetworkError : public StringError
@@ -216,6 +216,9 @@ public:
 	{}
 };
 
+/** @class KDMError
+ *  @brief A problem with a KDM.
+ */
 class KDMError : public StringError
 {
 public:
@@ -224,22 +227,30 @@ public:
 	{}
 };
 
+/** @class PixelFormatError
+ *  @brief A problem with an unsupported pixel format.
+ */
 class PixelFormatError : public StringError
 {
 public:
 	PixelFormatError (std::string o, AVPixelFormat f);
 };
 
-/** An error that occurs while parsing a SubRip file */
+/** @class SubRipError
+ *  @brief An error that occurs while parsing a SubRip file.
+ */
 class SubRipError : public FileError
 {
 public:
 	SubRipError (std::string, std::string, boost::filesystem::path);
 };
 
-/** A parent class for classes which have a need to catch and
- *  re-throw exceptions.  This is intended for classes
- *  which run their own thread; they should do something like
+/** @class ExceptionStore
+ *  @brief A parent class for classes which have a need to catch and
+ *  re-throw exceptions.
+
+ *  This is intended for classes which run their own thread; they should do
+ *  something like
  *
  *  void my_thread ()
  *  try {
diff --git a/src/lib/file_group.cc b/src/lib/file_group.cc
index 9d042554c..54ec8280c 100644
--- a/src/lib/file_group.cc
+++ b/src/lib/file_group.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,6 +17,10 @@
 
 */
 
+/** @file  src/lib/file_group.cc
+ *  @brief FileGroup class.
+ */
+
 #include <cstdio>
 #include <sndfile.h>
 #include "file_group.h"
@@ -26,6 +30,7 @@
 using std::vector;
 using std::cout;
 
+/** Construct a FileGroup with no files */
 FileGroup::FileGroup ()
 	: _current_path (0)
 	, _current_file (0)
@@ -33,14 +38,17 @@ FileGroup::FileGroup ()
 
 }
 
+/** Construct a FileGroup with a single file */
 FileGroup::FileGroup (boost::filesystem::path p)
 	: _current_path (0)
 	, _current_file (0)
 {
 	_paths.push_back (p);
+	ensure_open_path (0);
 	seek (0, SEEK_SET);
 }
 
+/** Construct a FileGroup with multiple files */
 FileGroup::FileGroup (vector<boost::filesystem::path> const & p)
 	: _paths (p)
 	, _current_path (0)
@@ -50,6 +58,7 @@ FileGroup::FileGroup (vector<boost::filesystem::path> const & p)
 	seek (0, SEEK_SET);
 }
 
+/** Destroy a FileGroup, closing any open file */
 FileGroup::~FileGroup ()
 {
 	if (_current_file) {
@@ -160,6 +169,7 @@ FileGroup::read (uint8_t* buffer, int amount) const
 	return read;
 }
 
+/** @return Combined length of all the files */
 int64_t
 FileGroup::length () const
 {
diff --git a/src/lib/file_group.h b/src/lib/file_group.h
index 65091c936..5a65de96f 100644
--- a/src/lib/file_group.h
+++ b/src/lib/file_group.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,12 +17,19 @@
 
 */
 
+/** @file  src/lib/file_group.h
+ *  @brief FileGroup class.
+ */
+
 #ifndef DCPOMATIC_FILE_GROUP_H
 #define DCPOMATIC_FILE_GROUP_H
 
 #include <vector>
 #include <boost/filesystem.hpp>
 
+/** @class FileGroup
+ *  @brief A class to make a list of files behave like they were concatenated.
+ */
 class FileGroup
 {
 public:
diff --git a/src/lib/player.h b/src/lib/player.h
index 9151d20c5..e47cf53a1 100644
--- a/src/lib/player.h
+++ b/src/lib/player.h
@@ -75,7 +75,8 @@ public:
 	void dump (boost::shared_ptr<Log>) const;
 };
 
-/** A wrapper for an Image which contains some pending operations; these may
+/** @class PlayerImage
+ *  @brief A wrapper for an Image which contains some pending operations; these may
  *  not be necessary if the receiver of the PlayerImage throws it away.
  */
 class PlayerImage
diff --git a/src/lib/playlist.h b/src/lib/playlist.h
index 444eb9ae5..4295a3e35 100644
--- a/src/lib/playlist.h
+++ b/src/lib/playlist.h
@@ -38,18 +38,15 @@ class Job;
 class Film;
 class Region;
 
-/** @class Playlist
- *  @brief A set of content files (video and audio), with knowledge of how they should be arranged into
- *  a DCP.
- *
- * This class holds Content objects, and it knows how they should be arranged.
- */
-
 struct ContentSorter
 {
 	bool operator() (boost::shared_ptr<Content> a, boost::shared_ptr<Content> b);
 };
 
+/** @class Playlist
+ *  @brief A set of Content objects with knowledge of how they should be arranged into
+ *  a DCP.
+ */
 class Playlist : public boost::noncopyable
 {
 public:
diff --git a/src/lib/position.h b/src/lib/position.h
index f9bd0987c..d68fcb1af 100644
--- a/src/lib/position.h
+++ b/src/lib/position.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
@@ -21,7 +21,7 @@
 #define DCPOMATIC_POSITION_H
 
 /** @struct Position
- *  @brief A position.
+ *  @brief A position (x and y coordinates)
  */
 template <class T>
 class Position
diff --git a/src/lib/update.cc b/src/lib/update.cc
index a98ee5b5d..019db8e76 100644
--- a/src/lib/update.cc
+++ b/src/lib/update.cc
@@ -34,6 +34,7 @@ using std::string;
 using std::stringstream;
 using boost::lexical_cast;
 
+/** Singleton instance */
 UpdateChecker* UpdateChecker::_instance = 0;
 
 static size_t
@@ -42,6 +43,9 @@ write_callback_wrapper (void* data, size_t size, size_t nmemb, void* user)
 	return reinterpret_cast<UpdateChecker*>(user)->write_callback (data, size, nmemb);
 }
 
+/** Construct an UpdateChecker.  This sets things up and starts a thread to
+ *  do the work.
+ */
 UpdateChecker::UpdateChecker ()
 	: _buffer (new char[BUFFER_SIZE])
 	, _offset (0)
@@ -73,6 +77,7 @@ UpdateChecker::~UpdateChecker ()
 	delete[] _buffer;
 }
 
+/** Start running the update check */
 void
 UpdateChecker::run ()
 {
@@ -85,6 +90,7 @@ void
 UpdateChecker::thread ()
 {
 	while (1) {
+		/* Block until there is something to do */
 		boost::mutex::scoped_lock lock (_process_mutex);
 		while (_to_do == 0) {
 			_condition.wait (lock);
@@ -94,12 +100,16 @@ UpdateChecker::thread ()
 		
 		try {
 			_offset = 0;
+
+			/* Perform the request */
 			
 			int r = curl_easy_perform (_curl);
 			if (r != CURLE_OK) {
 				set_state (FAILED);
 				return;
 			}
+
+			/* Parse the reply */
 			
 			_buffer[_offset] = '\0';
 			stringstream s;
diff --git a/src/lib/update.h b/src/lib/update.h
index e96ccec31..c86adb873 100644
--- a/src/lib/update.h
+++ b/src/lib/update.h
@@ -17,12 +17,17 @@
 
 */
 
+/** @file  src/lib/update.h
+ *  @brief UpdateChecker class.
+ */
+
 #include <boost/signals2.hpp>
 #include <boost/thread/mutex.hpp>
 #include <boost/thread/condition.hpp>
 #include <boost/thread.hpp>
 #include <curl/curl.h>
 
+/** Class to check for the existance of an update for DCP-o-matic on a remote server */
 class UpdateChecker
 {
 public:
@@ -32,28 +37,31 @@ public:
 	void run ();
 
 	enum State {
-		YES,
-		FAILED,
-		NO,
-		NOT_RUN
+		YES,    ///< there is an update
+		FAILED, ///< the check failed, so we don't know
+		NO,     ///< there is no update
+		NOT_RUN ///< the check has not been run (yet)
 	};
 
+	/** @return state of the checker */
 	State state () {
 		boost::mutex::scoped_lock lm (_data_mutex);
 		return _state;
 	}
 	
+	/** @return the version string of the latest stable version (if _state == YES or NO) */
 	std::string stable () {
 		boost::mutex::scoped_lock lm (_data_mutex);
 		return _stable;
 	}
 
+	/** @return the version string of the latest test version (if _state == YES or NO) */
 	std::string test () {
 		boost::mutex::scoped_lock lm (_data_mutex);
 		return _test;
 	}
 	
-	/** @return true if the list signal emission was the first */
+	/** @return true if the last signal emission was the first */
 	bool last_emit_was_first () const {
 		boost::mutex::scoped_lock lm (_data_mutex);
 		return _emits == 1;
diff --git a/src/lib/video_decoder.cc b/src/lib/video_decoder.cc
index 146120fe1..1b6da8a91 100644
--- a/src/lib/video_decoder.cc
+++ b/src/lib/video_decoder.cc
@@ -53,6 +53,11 @@ VideoDecoder::decoded_video (VideoFrame frame)
 	return output;
 }
 
+/** Get all frames which exist in the content at a given frame index.
+ *  @param frame Frame index.
+ *  @param accurate true to try hard to return frames at the precise time that was requested, otherwise frames nearby may be returned.
+ *  @return Frames; there may be none (if there is no video there), 1 for 2D or 2 for 3D.
+ */
 list<ContentVideo>
 VideoDecoder::get_video (VideoFrame frame, bool accurate)
 {
diff --git a/src/lib/video_decoder.h b/src/lib/video_decoder.h
index 685b72bc8..145baa40b 100644
--- a/src/lib/video_decoder.h
+++ b/src/lib/video_decoder.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/lib/video_decoder.h
+ *  @brief VideoDecoder class.
+ */
+
 #ifndef DCPOMATIC_VIDEO_DECODER_H
 #define DCPOMATIC_VIDEO_DECODER_H
 
@@ -30,6 +34,9 @@
 class VideoContent;
 class Image;
 
+/** @class VideoDecoder
+ *  @brief Parent for classes which decode video.
+ */
 class VideoDecoder : public virtual Decoder
 {
 public:
diff --git a/src/lib/video_examiner.h b/src/lib/video_examiner.h
index d4897213b..87e9a0428 100644
--- a/src/lib/video_examiner.h
+++ b/src/lib/video_examiner.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,10 +17,17 @@
 
 */
 
+/** @file  src/lib/video_examiner.h
+ *  @brief VideoExaminer class.
+ */
+
 #include <dcp/types.h>
 #include "types.h"
 #include "video_content.h"
 
+/** @class VideoExaminer
+ *  @brief Parent for classes which examine video sources and obtain information about them.
+ */
 class VideoExaminer
 {
 public: