No-op; comments.

6 files changed, 62 insertions, 3 deletions

diff --git a/src/lib/film.h b/src/lib/film.h
index a1cf26bc6..ae0ad7ad1 100644
--- a/src/lib/film.h
+++ b/src/lib/film.h
@@ -76,6 +76,7 @@ public:
 		return _state.dcp_name ();
 	}
 
+	/** @return true to use a DCI-spec name for the DCP */
 	bool use_dci_name () const {
 		return _state.use_dci_name;
 	}
@@ -105,6 +106,7 @@ public:
 		return _state.dcp_frames;
 	}
 
+	/** @return what to do with the end of an encode when trimming */
 	TrimAction dcp_trim_action () const {
 		return _state.dcp_trim_action;
 	}
@@ -117,26 +119,36 @@ public:
 		return _state.dcp_ab;
 	}
 
+	/** @return gain that should be applied to the audio when making a DCP
+	    (in dB).
+	*/
 	float audio_gain () const {
 		return _state.audio_gain;
 	}
 
+	/** @return delay to apply to audio (positive moves audio later) in milliseconds */
 	int audio_delay () const {
 		return _state.audio_delay;
 	}
 
+	/** @return duration to make still-sourced films (in seconds) */
 	int still_duration () const {
 		return _state.still_duration;
 	}
 
+	/** @return true to encode DCP with subtitles, if they are available */
 	bool with_subtitles () const {
 		return _state.with_subtitles;
 	}
 
+	/** @return offset to move subtitles by, in source pixels; +ve moves
+	    them down the image, -ve moves them up.
+	*/
 	int subtitle_offset () const {
 		return _state.subtitle_offset;
 	}
 
+	/** @return scaling factor to apply to subtitle images */
 	float subtitle_scale () const {
 		return _state.subtitle_scale;
 	}
diff --git a/src/lib/film_state.cc b/src/lib/film_state.cc
index ca43790f2..aa8bb5563 100644
--- a/src/lib/film_state.cc
+++ b/src/lib/film_state.cc
@@ -355,6 +355,7 @@ FilmState::dcp_length () const
 	return length;
 }
 
+/** @return a DCI-compliant name for a DCP of this film */
 string
 FilmState::dci_name () const
 {
@@ -367,6 +368,7 @@ FilmState::dci_name () const
 		}
 	}
 
+	/* Spec is that the name part should be maximum 14 characters, as I understand it */
 	if (fixed_name.length() > 14) {
 		fixed_name = fixed_name.substr (0, 14);
 	}
diff --git a/src/lib/film_state.h b/src/lib/film_state.h
index 01bcdfd5c..ea287fb3b 100644
--- a/src/lib/film_state.h
+++ b/src/lib/film_state.h
@@ -103,6 +103,7 @@ public:
 	std::string directory;
 	/** Name for DVD-o-matic */
 	std::string name;
+	/** True if a auto-generated DCI-compliant name should be used for our DCP */
 	bool use_dci_name;
 	/** File or directory containing content; may be relative to our directory
 	 *  or an absolute path.
@@ -135,11 +136,13 @@ public:
 	int audio_delay;
 	/** Duration to make still-sourced films (in seconds) */
 	int still_duration;
+	/** True if subtitles should be shown for this film */
 	bool with_subtitles;
 	/** y offset for placing subtitles, in source pixels; +ve is further down
 	    the frame, -ve is further up.
 	*/
 	int subtitle_offset;
+	/** scale factor to apply to subtitles */
 	float subtitle_scale;
 
 	/* DCI naming stuff */
diff --git a/src/lib/subtitle.cc b/src/lib/subtitle.cc
index 01e8cac13..dcb747828 100644
--- a/src/lib/subtitle.cc
+++ b/src/lib/subtitle.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/subtitle.cc
+ *  @brief Representations of subtitles.
+ */
+
 #include "subtitle.h"
 #include "image.h"
 #include "exceptions.h"
@@ -25,6 +29,10 @@
 using namespace std;
 using namespace boost;
 
+/** Construct a TimedSubtitle.  This is a subtitle image, position,
+ *  and a range of time over which it should be shown.
+ *  @param sub AVSubtitle to read.
+ */
 TimedSubtitle::TimedSubtitle (AVSubtitle const & sub)
 {
 	/* subtitle PTS in seconds */
@@ -73,13 +81,27 @@ TimedSubtitle::displayed_at (double t) const
 	return t >= _from && t <= _to;
 }
 
+/** Construct a subtitle, which is an image and a position.
+ *  @param p Position within the (uncropped) source frame.
+ *  @param i Image of the subtitle (should be RGBA).
+ */
 Subtitle::Subtitle (Position p, shared_ptr<Image> i)
 	: _position (p)
 	, _image (i)
 {
 
 }
-	
+
+/** Given the area of a subtitle, work out the area it should
+ *  take up when its video frame is scaled up, and it is optionally
+ *  itself scaled and offset.
+ *  @param target_x_scale the x scaling of the video frame that the subtitle is in.
+ *  @param target_y_scale the y scaling of the video frame that the subtitle is in.
+ *  @param sub_area The area of the subtitle within the original source.
+ *  @param subtitle_offset y offset to apply to the subtitle position (+ve is down)
+ *  in the coordinate space of the source.
+ *  @param subtitle_scale scaling factor to apply to the subtitle image.
+ */
 Rectangle
 subtitle_transformed_area (
 	float target_x_scale, float target_y_scale,
@@ -114,6 +136,7 @@ subtitle_transformed_area (
 	return tx;
 }
 
+/** @return area that this subtitle take up, in the original uncropped source's coordinate space */
 Rectangle
 Subtitle::area () const
 {
diff --git a/src/lib/subtitle.h b/src/lib/subtitle.h
index de8f02596..1cc906ce0 100644
--- a/src/lib/subtitle.h
+++ b/src/lib/subtitle.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/subtitle.h
+ *  @brief Representations of subtitles.
+ */
+
 #include <list>
 #include <boost/shared_ptr.hpp>
 #include "util.h"
@@ -24,6 +28,7 @@
 struct AVSubtitle;
 class Image;
 
+/** A subtitle, consisting of an image and a position */
 class Subtitle
 {
 public:
@@ -53,7 +58,8 @@ subtitle_transformed_area (
 	float target_x_scale, float target_y_scale,
 	Rectangle sub_area, int subtitle_offset, float subtitle_scale
 	);
-	
+
+/** A Subtitle class with details of the time over which it should be shown */
 class TimedSubtitle
 {
 public:
@@ -66,8 +72,8 @@ public:
 	}
 
 private:
+	/** the subtitle */
 	boost::shared_ptr<Subtitle> _subtitle;
-	
 	/** display from time in seconds from the start of the film */
 	double _from;
 	/** display to time in seconds from the start of the film */
diff --git a/src/lib/util.cc b/src/lib/util.cc
index 9a0a8be82..cc201a0af 100644
--- a/src/lib/util.cc
+++ b/src/lib/util.cc
@@ -615,6 +615,12 @@ Rectangle::intersection (Rectangle const & other) const
 		);
 }
 
+/** Round a number up to the nearest multiple of another number.
+ *  @param a Number to round.
+ *  @param t Multiple to round to.
+ *  @return Rounded number.
+ */
+
 int
 round_up (int a, int t)
 {
@@ -622,6 +628,13 @@ round_up (int a, int t)
 	return a - (a % t);
 }
 
+/** Read a sequence of key / value pairs from a text stream;
+ *  the keys are the first words on the line, and the values are
+ *  the remainder of the line following the key.  Lines beginning
+ *  with # are ignored.
+ *  @param s Stream to read.
+ *  @return key/value pairs.
+ */
 multimap<string, string>
 read_key_value (istream &s) 
 {