Remove unused Processor::process_begin; some docs.

11 files changed, 117 insertions, 11 deletions

diff --git a/src/lib/config.h b/src/lib/config.h
index 59af8a07a..62cababfb 100644
--- a/src/lib/config.h
+++ b/src/lib/config.h
@@ -107,6 +107,7 @@ public:
 		return _tms_password;
 	}
 
+	/** @return The sound processor that we are using */
 	SoundProcessor const * sound_processor () const {
 		return _sound_processor;
 	}
diff --git a/src/lib/filter_graph.cc b/src/lib/filter_graph.cc
index aaa9e07ba..7320070fe 100644
--- a/src/lib/filter_graph.cc
+++ b/src/lib/filter_graph.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file src/lib/filter_graph.cc
+ *  @brief A graph of FFmpeg filters.
+ */
+
 extern "C" {
 #include <libavfilter/avfiltergraph.h>
 #include <libavfilter/buffersrc.h>
@@ -42,6 +46,13 @@ using std::string;
 using std::list;
 using boost::shared_ptr;
 
+/** Construct a FilterGraph for the settings in a film.
+ *  @param film Film.
+ *  @param decoder Decoder that we are using.
+ *  @param crop true to apply crop, otherwise false.
+ *  @param s Size of the images to process.
+ *  @param p Pixel format of the images to process.
+ */
 FilterGraph::FilterGraph (shared_ptr<Film> film, FFmpegDecoder* decoder, bool crop, Size s, AVPixelFormat p)
 	: _buffer_src_context (0)
 	, _buffer_sink_context (0)
@@ -127,6 +138,9 @@ FilterGraph::FilterGraph (shared_ptr<Film> film, FFmpegDecoder* decoder, bool cr
 	/* XXX: leaking `inputs' / `outputs' ? */
 }
 
+/** Take an AVFrame and process it using our configured filters, returning a
+ *  set of Images.
+ */
 list<shared_ptr<Image> >
 FilterGraph::process (AVFrame const * frame)
 {
@@ -189,6 +203,10 @@ FilterGraph::process (AVFrame const * frame)
 	return images;
 }
 
+/** @param s Image size.
+ *  @param p Pixel format.
+ *  @return true if this chain can process images with `s' and `p', otherwise false.
+ */
 bool
 FilterGraph::can_process (Size s, AVPixelFormat p) const
 {
diff --git a/src/lib/filter_graph.h b/src/lib/filter_graph.h
index 5c0c83d16..3842e9f7d 100644
--- a/src/lib/filter_graph.h
+++ b/src/lib/filter_graph.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file src/lib/filter_graph.h
+ *  @brief A graph of FFmpeg filters.
+ */
+
 #ifndef DVDOMATIC_FILTER_GRAPH_H
 #define DVDOMATIC_FILTER_GRAPH_H
 
@@ -26,6 +30,9 @@ class Image;
 class VideoFilter;
 class FFmpegDecoder;
 
+/** @class FilterGraph
+ *  @brief A graph of FFmpeg filters.
+ */
 class FilterGraph
 {
 public:
@@ -37,8 +44,8 @@ public:
 private:
 	AVFilterContext* _buffer_src_context;
 	AVFilterContext* _buffer_sink_context;
-	Size _size;
-	AVPixelFormat _pixel_format;
+	Size _size; ///< size of the images that this chain can process
+	AVPixelFormat _pixel_format; ///< pixel format of the images that this chain can process
 };
 
 #endif
diff --git a/src/lib/job.cc b/src/lib/job.cc
index 3309fe16c..201397f08 100644
--- a/src/lib/job.cc
+++ b/src/lib/job.cc
@@ -33,6 +33,7 @@ using std::stringstream;
 using boost::shared_ptr;
 
 /** @param s Film that we are operating on.
+ *  @param req Job that must be completed before this job is run.
  */
 Job::Job (shared_ptr<Film> f, shared_ptr<Job> req)
 	: _film (f)
@@ -77,6 +78,7 @@ Job::run_wrapper ()
 	}
 }
 
+/** @return true if this job is new (ie has not started running) */
 bool
 Job::is_new () const
 {
diff --git a/src/lib/processor.h b/src/lib/processor.h
index cddcbf3f1..e632f813f 100644
--- a/src/lib/processor.h
+++ b/src/lib/processor.h
@@ -37,15 +37,18 @@ class Log;
 class Processor
 {
 public:
+	/** Construct a Processor.
+	 *  @param log Log to use.
+	 */
 	Processor (Log* log)
 		: _log (log)
 	{}
-	
-	virtual void process_begin () {}
+
+	/** Will be called at the end of a processing run */
 	virtual void process_end () {}
 
 protected:
-	Log* _log;
+	Log* _log; ///< log to write to
 };
 
 /** @class AudioVideoProcessor
@@ -54,6 +57,9 @@ protected:
 class AudioVideoProcessor : public Processor, public VideoSource, public VideoSink, public AudioSource, public AudioSink
 {
 public:
+	/** Construct an AudioVideoProcessor.
+	 *  @param log Log to write to.
+	 */
 	AudioVideoProcessor (Log* log)
 		: Processor (log)
 	{}
@@ -65,6 +71,9 @@ public:
 class AudioProcessor : public Processor, public AudioSource, public AudioSink
 {
 public:
+	/** Construct an AudioProcessor.
+	 *  @param log Log to write to.
+	 */
 	AudioProcessor (Log* log)
 		: Processor (log)
 	{}
@@ -76,6 +85,9 @@ public:
 class VideoProcessor : public Processor, public VideoSource, public VideoSink
 {
 public:
+	/** Construct an VideoProcessor.
+	 *  @param log Log to write to.
+	 */
 	VideoProcessor (Log* log)
 		: Processor (log)
 	{}
diff --git a/src/lib/stream.cc b/src/lib/stream.cc
index 372077cd8..4f12f41b9 100644
--- a/src/lib/stream.cc
+++ b/src/lib/stream.cc
@@ -28,6 +28,10 @@ using std::stringstream;
 using boost::shared_ptr;
 using boost::optional;
 
+/** Construct a SubtitleStream from a value returned from to_string().
+ *  @param t String returned from to_string().
+ *  @param v State file version.
+ */
 SubtitleStream::SubtitleStream (string t, boost::optional<int>)
 {
 	stringstream n (t);
@@ -39,18 +43,28 @@ SubtitleStream::SubtitleStream (string t, boost::optional<int>)
 	}
 }
 
+/** @return A canonical string representation of this stream */
 string
 SubtitleStream::to_string () const
 {
 	return String::compose ("%1 %2", _id, _name);
 }
 
+/** Create a SubtitleStream from a value returned from to_string().
+ *  @param t String returned from to_string().
+ *  @param v State file version.
+ */
 shared_ptr<SubtitleStream>
 SubtitleStream::create (string t, optional<int> v)
 {
 	return shared_ptr<SubtitleStream> (new SubtitleStream (t, v));
 }
 
+/** Create an AudioStream from a string returned from to_string().
+ *  @param t String returned from to_string().
+ *  @param v State file version.
+ *  @return AudioStream, or 0.
+ */
 shared_ptr<AudioStream>
 audio_stream_factory (string t, optional<int> v)
 {
@@ -64,6 +78,11 @@ audio_stream_factory (string t, optional<int> v)
 	return s;
 }
 
+/** Create a SubtitleStream from a string returned from to_string().
+ *  @param t String returned from to_string().
+ *  @param v State file version.
+ *  @return SubtitleStream, or 0.
+ */
 shared_ptr<SubtitleStream>
 subtitle_stream_factory (string t, optional<int> v)
 {
diff --git a/src/lib/stream.h b/src/lib/stream.h
index 5dd91f5f4..c2a19e5ab 100644
--- a/src/lib/stream.h
+++ b/src/lib/stream.h
@@ -17,6 +17,14 @@
 
 */
 
+/** @file src/lib/stream.h
+ *  @brief Representations of audio and subtitle streams.
+ *
+ *  Some content may have multiple `streams' of audio and/or subtitles; perhaps
+ *  for multiple languages, or for stereo / surround mixes.  These classes represent
+ *  those streams, and know about their details.
+ */
+
 #ifndef DVDOMATIC_STREAM_H
 #define DVDOMATIC_STREAM_H
 
@@ -27,12 +35,18 @@ extern "C" {
 #include <libavutil/audioconvert.h>
 }
 
+/** @class Stream
+ *  @brief Parent class for streams.
+ */
 class Stream
 {
 public:
 	virtual std::string to_string () const = 0;
 };
 
+/** @class AudioStream
+ *  @brief A stream of audio data.
+ */
 struct AudioStream : public Stream
 {
 public:
@@ -68,6 +82,9 @@ protected:
 	int64_t _channel_layout;
 };
 
+/** @class SubtitleStream
+ *  @brief A stream of subtitle data.
+ */
 class SubtitleStream : public Stream
 {
 public:
diff --git a/src/lib/transcode_job.cc b/src/lib/transcode_job.cc
index 5e9e58667..081e04252 100644
--- a/src/lib/transcode_job.cc
+++ b/src/lib/transcode_job.cc
@@ -39,6 +39,7 @@ using boost::shared_ptr;
 
 /** @param s Film to use.
  *  @param o Options.
+ *  @param req Job that must be completed before this job is run.
  */
 TranscodeJob::TranscodeJob (shared_ptr<Film> f, shared_ptr<const Options> o, shared_ptr<Job> req)
 	: Job (f, req)
diff --git a/src/lib/util.cc b/src/lib/util.cc
index 29ba91f7c..bb33eb431 100644
--- a/src/lib/util.cc
+++ b/src/lib/util.cc
@@ -291,6 +291,10 @@ dvdomatic_setup ()
 #endif	
 }
 
+/** @param start Start position for the crop within the image.
+ *  @param size Size of the cropped area.
+ *  @return FFmpeg crop filter string.
+ */
 string
 crop_string (Position start, Size size)
 {
@@ -299,6 +303,9 @@ crop_string (Position start, Size size)
 	return s.str ();
 }
 
+/** @param s A string.
+ *  @return Parts of the string split at spaces, except when a space is within quotation marks.
+ */
 vector<string>
 split_at_spaces_considering_quotes (string s)
 {
@@ -375,6 +382,9 @@ md5_digest (string file)
 	return s.str ();
 }
 
+/** @param fps Arbitrary frames-per-second value.
+ *  @return DCPFrameRate for this frames-per-second.
+ */
 DCPFrameRate
 dcp_frame_rate (float fps)
 {
@@ -601,6 +611,9 @@ Socket::read_indefinite (uint8_t* data, int size, int timeout)
 	memcpy (data, _buffer, size);
 }
 
+/** @param other A Rect.
+ *  @return The intersection of this with `other'.
+ */
 Rect
 Rect::intersection (Rect const & other) const
 {
@@ -619,7 +632,6 @@ Rect::intersection (Rect const & other) const
  *  @param t Multiple to round to.
  *  @return Rounded number.
  */
-
 int
 stride_round_up (int c, int const * stride, int t)
 {
@@ -760,6 +772,7 @@ AudioBuffers::AudioBuffers (AudioBuffers const & other)
 	}
 }
 
+/** AudioBuffers destructor */
 AudioBuffers::~AudioBuffers ()
 {
 	for (int i = 0; i < _channels; ++i) {
diff --git a/src/lib/util.h b/src/lib/util.h
index 341458155..68c7bd384 100644
--- a/src/lib/util.h
+++ b/src/lib/util.h
@@ -41,6 +41,7 @@ extern "C" {
 #define TIMING(...)
 #endif
 
+/** The maximum number of audio channels that we can cope with */
 #define MAX_AUDIO_CHANNELS 6
 
 class Scaler;
@@ -60,14 +61,21 @@ typedef int SourceFrame;
 
 struct DCPFrameRate
 {
+	/** frames per second for the DCP */
 	int frames_per_second;
+	/** Skip every `skip' frames.  e.g. if this is 1, we skip nothing;
+	 *  if it's 2, we skip every other frame.
+	 */
 	int skip;
+	/** true if this DCP will run its video faster than the source
+	 *  (e.g. if the source is 29.97fps and we will run the DCP at 30fps)
+	 */
 	bool run_fast;
 };
 
 enum ContentType {
-	STILL,
-	VIDEO
+	STILL, ///< content is still images
+	VIDEO  ///< content is a video
 };
 
 /** @class Size
@@ -96,7 +104,9 @@ struct Size
 
 extern bool operator== (Size const & a, Size const & b);
 
-/** A description of the crop of an image or video. */
+/** @struct Crop
+ *  @brief A description of the crop of an image or video.
+ */
 struct Crop
 {
 	Crop () : left (0), right (0), top (0), bottom (0) {}
@@ -114,7 +124,9 @@ struct Crop
 extern bool operator== (Crop const & a, Crop const & b);
 extern bool operator!= (Crop const & a, Crop const & b);
 
-/** A position */
+/** @struct Position
+ *  @brief A position.
+ */
 struct Position
 {
 	Position ()
@@ -133,7 +145,9 @@ struct Position
 	int y;
 };
 
-/** A rectangle */
+/** @struct Rect
+ *  @brief A rectangle.
+ */
 struct Rect
 {
 	Rect ()
diff --git a/src/lib/video_decoder.h b/src/lib/video_decoder.h
index 5acce7c8d..ea1899840 100644
--- a/src/lib/video_decoder.h
+++ b/src/lib/video_decoder.h
@@ -63,7 +63,9 @@ protected:
 	void emit_subtitle (boost::shared_ptr<TimedSubtitle>);
 	void repeat_last_video ();
 
+	/** Subtitle stream to use when decoding */
 	boost::shared_ptr<SubtitleStream> _subtitle_stream;
+	/** Subtitle streams that this decoder's content has */
 	std::vector<boost::shared_ptr<SubtitleStream> > _subtitle_streams;
 
 private: