Various Doxygen fixes.

91 files changed, 295 insertions, 93 deletions

diff --git a/Doxyfile b/Doxyfile
index e9b682752..dd890691a 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -714,14 +714,14 @@ QUIET                  = YES
 # Tip: Turn warnings on while writing the documentation.
 # The default value is: YES.
 
-WARNINGS               = YES
+WARNINGS               = NO
 
 # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
 # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index 20d962c8f..81f8a6ee2 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -1,31 +1,26 @@
 /** @mainpage DCP-o-matic
  *
  *  DCP-o-matic is a tool to create digital cinema packages (DCPs) from
- *  video files, or from sets of image files.  It is written in C++
+ *  video files, sets of image files, sound and subtitle files.  It is written in C++
  *  and distributed under the GPL.
  *
- *  Video and sound files are decoded using FFmpeg (http://ffmpeg.org), so any file
- *  supported by FFmpeg should be usable with DCP-o-matic.  DCP-o-matic's output has been
- *  tested on numerous digital projectors.
- *
- *  DCP-o-matic allows you to crop black borders from movies, scale them to the correct
- *  aspect ratio and apply FFmpeg filters.  The time-consuming encoding of JPEG2000 files
- *  can be parallelised amongst any number of processors on the local host and any number
- *  of servers over a network.
+ *  More details can be found at https://dcpomatic.com/
  *
- *  DCP-o-matic can also make DCPs from still images, for advertisements and such-like.
+ *  The source is split into four main parts:
  *
- *  Parts of DCP-o-matic are based on OpenDCP (http://code.google.com/p/opendcp),
- *  written by Terrence Meiczinger.
+ *  Directory   | Description
+ *  ------------|---------------------------------------------------------------------------------------------
+ *  `src/lib`   | ‘backend’ library with no user interface code.
+ *  `src/wx`    | wxWidgets front end code that is common to all tools.
+ *  `src/tools` | Command line and GUI front-ends for the separate tools (main DCP-o-matic, KDM creator etc.)
+ *  `test`      | Unit tests
  *
- *  DCP-o-matic uses libopenjpeg (http://code.google.com/p/openjpeg/) for JPEG2000 encoding
- *  and ImageMagick (http://www.imagemagick.org/) for still-image encoding and decoding.
- *  It also uses the boost libraries (http://www.boost.org/) and the GUI is
- *  built using wxWidgets (http://wxwidgets.org/).
+ * It is build with `waf`, using something like \code
  *
- *  Thanks are due to the authors and communities of all DCP-o-matic's dependencies.
+ * ./waf configure --enable-debug --prefix=/opt
+ * ./waf -j4
+ * sudo ./waf install
  *
- *  Email correspondance is welcome to carl@dcpomatic.com
+ * \endcode
  *
- *  More details can be found at https://dcpomatic.com/
  */
diff --git a/src/lib/audio_buffers.cc b/src/lib/audio_buffers.cc
index aea581a07..825c6c2f3 100644
--- a/src/lib/audio_buffers.cc
+++ b/src/lib/audio_buffers.cc
@@ -224,6 +224,9 @@ AudioBuffers::move (int32_t frames, int32_t from, int32_t to)
 }
 
 /** Add data from from `from', `from_channel' to our channel `to_channel'.
+ *  @param from Buffers to copy data from.
+ *  @param from_channel Channel index to read in \p from.
+ *  @param to_channel Channel index to accumulate into.
  *  @param gain Linear gain to apply to the data before it is added.
  */
 void
diff --git a/src/lib/audio_buffers.h b/src/lib/audio_buffers.h
index 991ef5334..f4a0c1f1c 100644
--- a/src/lib/audio_buffers.h
+++ b/src/lib/audio_buffers.h
@@ -32,7 +32,7 @@
  *  @brief A class to hold multi-channel audio data in float format.
  *
  *  The use of int32_t for frame counts in this class is due to the
- *  round-up to the next power-of-2 code in ::ensure_size; if that
+ *  round-up to the next power-of-2 code in ensure_size(); if that
  *  were changed the frame count could use any integer type.
  */
 class AudioBuffers
diff --git a/src/lib/cinema_kdms.cc b/src/lib/cinema_kdms.cc
index 8cac65f41..605e414a0 100644
--- a/src/lib/cinema_kdms.cc
+++ b/src/lib/cinema_kdms.cc
@@ -178,6 +178,10 @@ CinemaKDMs::write_zip_files (
 }
 
 /** Email one ZIP file per cinema to the cinema.
+ *  @param cinema_kdms KDMS to email.
+ *  @param name_format Format of filename to use.
+ *  @param name_values Values to substitute into \p name_format.
+ *  @param cpl_name Name of the CPL that the KDMs are for.
  *  @param log Log to write email session transcript to, or 0.
  */
 void
diff --git a/src/lib/config.h b/src/lib/config.h
index 80dfb1dc9..ed29a8f24 100644
--- a/src/lib/config.h
+++ b/src/lib/config.h
@@ -550,7 +550,7 @@ public:
 
 	void changed (Property p = OTHER);
 	boost::signals2::signal<void (Property)> Changed;
-	/** Emitted if ::read() failed on an existing Config file.  There is nothing
+	/** Emitted if read() failed on an existing Config file.  There is nothing
 	    a listener can do about it: this is just for information.
 	*/
 	static boost::signals2::signal<void ()> FailedToLoad;
diff --git a/src/lib/content.h b/src/lib/content.h
index 519ff8907..334a82756 100644
--- a/src/lib/content.h
+++ b/src/lib/content.h
@@ -121,7 +121,7 @@ public:
 
 	/** @return Digest of the content's file(s).  Note: this is
 	 *  not a complete MD5-or-whatever hash, but a sort of poor
-	 *  man's version (see comments in ::examine).
+	 *  man's version (see comments in examine()).
 	 */
 	std::string digest () const {
 		boost::mutex::scoped_lock lm (_mutex);
diff --git a/src/lib/cross.h b/src/lib/cross.h
index c7bb4991c..9fac7e643 100644
--- a/src/lib/cross.h
+++ b/src/lib/cross.h
@@ -53,7 +53,7 @@ extern uint64_t thread_id ();
 /** @class Waker
  *  @brief A class which tries to keep the computer awake on various operating systems.
  *
- *  Create a Waker to prevent sleep, and call ::nudge every so often (every minute or so).
+ *  Create a Waker to prevent sleep, and call nudge() every so often (every minute or so).
  *  Destroy the Waker to allow sleep again.
  */
 class Waker
diff --git a/src/lib/dcp_video.cc b/src/lib/dcp_video.cc
index 5fbe6d169..ba8057be0 100644
--- a/src/lib/dcp_video.cc
+++ b/src/lib/dcp_video.cc
@@ -148,6 +148,7 @@ DCPVideo::encode_locally (dcp::NoteHandler note)
 
 /** Send this frame to a remote server for J2K encoding, then read the result.
  *  @param serv Server to send to.
+ *  @param timeout timeout in seconds.
  *  @return Encoded data.
  */
 Data
diff --git a/src/lib/dcpomatic_socket.cc b/src/lib/dcpomatic_socket.cc
index fa06918d4..ca910bb79 100644
--- a/src/lib/dcpomatic_socket.cc
+++ b/src/lib/dcpomatic_socket.cc
@@ -27,6 +27,7 @@
 
 #include "i18n.h"
 
+/** @param timeout Timeout in seconds */
 Socket::Socket (int timeout)
 	: _deadline (_io_service)
 	, _socket (_io_service)
diff --git a/src/lib/dcpomatic_time.h b/src/lib/dcpomatic_time.h
index cc31755cb..8b2bcce05 100644
--- a/src/lib/dcpomatic_time.h
+++ b/src/lib/dcpomatic_time.h
@@ -158,7 +158,13 @@ public:
 		return ::ceil (_t * double(r) / HZ);
 	}
 
-	/** @param r Frames per second */
+	/** Split a time into hours, minutes, seconds and frames.
+	 *  @param r Frames per second.
+	 *  @param h Returned hours.
+	 *  @param m Returned minutes.
+	 *  @param s Returned seconds.
+	 *  @param f Returned frames.
+	 */
 	template <typename T>
 	void split (T r, int& h, int& m, int& s, int& f) const
 	{
@@ -292,7 +298,9 @@ public:
 	}
 };
 
-/** @param B Periods to subtract from `A', must be in ascending order of start time and must not overlap */
+/** @param A Period which is subtracted from.
+ *  @param B Periods to subtract from `A', must be in ascending order of start time and must not overlap.
+ */
 template <class T>
 std::list<TimePeriod<T> > subtract (TimePeriod<T> A, std::list<TimePeriod<T> > const & B)
 {
diff --git a/src/lib/encoder.cc b/src/lib/encoder.cc
index a9e119d59..e43325f58 100644
--- a/src/lib/encoder.cc
+++ b/src/lib/encoder.cc
@@ -56,7 +56,9 @@ using dcp::Data;
 
 int const Encoder::_history_size = 200;
 
-/** @param f Film that we are encoding */
+/** @param film Film that we are encoding.
+ *  @param writer Writer that we are using.
+ */
 Encoder::Encoder (shared_ptr<const Film> film, shared_ptr<Writer> writer)
 	: _film (film)
 	, _writer (writer)
@@ -172,9 +174,7 @@ Encoder::video_frames_enqueued () const
 	return _last_player_video_time->frames_floor (_film->video_frame_rate ());
 }
 
-/** Should be called when a frame has been encoded successfully.
- *  @param n Source frame index.
- */
+/** Should be called when a frame has been encoded successfully */
 void
 Encoder::frame_done ()
 {
@@ -192,6 +192,9 @@ Encoder::frame_done ()
  *  so each time the supplied frame is the one after the previous one.
  *  pv represents one video frame, and could be empty if there is nothing to encode
  *  for this DCP frame.
+ *
+ *  @param pv PlayerVideo to encode.
+ *  @param time Time of \p pv within the DCP.
  */
 void
 Encoder::encode (shared_ptr<PlayerVideo> pv, DCPTime time)
diff --git a/src/lib/encoder.h b/src/lib/encoder.h
index 27ae64aac..fe18f8b2d 100644
--- a/src/lib/encoder.h
+++ b/src/lib/encoder.h
@@ -55,14 +55,14 @@ class PlayerVideo;
 class Encoder : public boost::noncopyable, public ExceptionStore, public boost::enable_shared_from_this<Encoder>
 {
 public:
-	Encoder (boost::shared_ptr<const Film>, boost::shared_ptr<Writer>);
+	Encoder (boost::shared_ptr<const Film> film, boost::shared_ptr<Writer> writer);
 	~Encoder ();
 
 	/** Called to indicate that a processing run is about to begin */
 	void begin ();
 
 	/** Called to pass a bit of video to be encoded as the next DCP frame */
-	void encode (boost::shared_ptr<PlayerVideo> f, DCPTime time);
+	void encode (boost::shared_ptr<PlayerVideo> pv, DCPTime time);
 
 	/** Called when a processing run has finished */
 	void end ();
diff --git a/src/lib/exceptions.h b/src/lib/exceptions.h
index 99a8c0dc4..c2f82e15b 100644
--- a/src/lib/exceptions.h
+++ b/src/lib/exceptions.h
@@ -167,7 +167,9 @@ public:
 class BadSettingError : public SettingError
 {
 public:
-	/** @param s Name of setting that is bad */
+	/** @param s Name of setting that is bad.
+	 *  @param m Error message.
+	 */
 	BadSettingError (std::string s, std::string m)
 		: SettingError (s, m)
 	{}
diff --git a/src/lib/ffmpeg_subtitle_stream.cc b/src/lib/ffmpeg_subtitle_stream.cc
index 62accfaf8..3935e23a9 100644
--- a/src/lib/ffmpeg_subtitle_stream.cc
+++ b/src/lib/ffmpeg_subtitle_stream.cc
@@ -32,8 +32,8 @@ using std::make_pair;
 using dcp::raw_convert;
 
 /** Construct a SubtitleStream from a value returned from to_string().
- *  @param t String returned from to_string().
- *  @param v State file version.
+ *  @param node String returned from to_string().
+ *  @param version State file version.
  */
 FFmpegSubtitleStream::FFmpegSubtitleStream (cxml::ConstNodePtr node, int version)
 	: FFmpegStream (node)
diff --git a/src/lib/ffmpeg_subtitle_stream.h b/src/lib/ffmpeg_subtitle_stream.h
index 704ac7b79..8b0274a5d 100644
--- a/src/lib/ffmpeg_subtitle_stream.h
+++ b/src/lib/ffmpeg_subtitle_stream.h
@@ -30,7 +30,7 @@ public:
 		: FFmpegStream (n, i)
 	{}
 
-	FFmpegSubtitleStream (cxml::ConstNodePtr, int version);
+	FFmpegSubtitleStream (cxml::ConstNodePtr node, int version);
 
 	void as_xml (xmlpp::Node *) const;
 
diff --git a/src/lib/film.cc b/src/lib/film.cc
index 56dce56e5..82a40d5c4 100644
--- a/src/lib/film.cc
+++ b/src/lib/film.cc
@@ -1207,8 +1207,12 @@ Film::frame_size () const
 	return fit_ratio_within (container()->ratio(), full_frame ());
 }
 
-/** @param from KDM from time expressed as a local time with an offset from UTC
- *  @param to KDM to time expressed as a local time with an offset from UTC
+/** @param recipient KDM recipient certificate.
+ *  @param trusted_devices Certificates of other trusted devices (can be empty).
+ *  @param cpl_file CPL filename.
+ *  @param from KDM from time expressed as a local time with an offset from UTC.
+ *  @param until KDM to time expressed as a local time with an offset from UTC.
+ *  @param formulation KDM formulation to use.
  */
 dcp::EncryptedKDM
 Film::make_kdm (
@@ -1267,13 +1271,16 @@ Film::make_kdm (
 		).encrypt (signer, recipient, trusted_devices, formulation);
 }
 
-/** @param from KDM from time expressed as a local time in the time zone of the Screen's Cinema.
- *  @param to KDM to time expressed as a local time in the time zone of the Screen's Cinema.
+/** @param screens Screens to make KDMs for.
+ *  @param cpl_file Path to CPL to make KDMs for.
+ *  @param from KDM from time expressed as a local time in the time zone of the Screen's Cinema.
+ *  @param until KDM to time expressed as a local time in the time zone of the Screen's Cinema.
+ *  @param formulation KDM formulation to use.
  */
 list<ScreenKDM>
 Film::make_kdms (
 	list<shared_ptr<Screen> > screens,
-	boost::filesystem::path dcp,
+	boost::filesystem::path cpl_file,
 	boost::posix_time::ptime from,
 	boost::posix_time::ptime until,
 	dcp::Formulation formulation
@@ -1286,7 +1293,7 @@ Film::make_kdms (
 			dcp::EncryptedKDM const kdm = make_kdm (
 				i->recipient.get(),
 				i->trusted_devices,
-				dcp,
+				cpl_file,
 				dcp::LocalTime (from, i->cinema->utc_offset_hour(), i->cinema->utc_offset_minute()),
 				dcp::LocalTime (until, i->cinema->utc_offset_hour(), i->cinema->utc_offset_minute()),
 				formulation
@@ -1510,6 +1517,9 @@ Film::reels () const
 	return p;
 }
 
+/** @param period A period within the DCP
+ *  @return Name of the content which most contributes to the given period.
+ */
 string
 Film::content_summary (DCPTimePeriod period) const
 {
diff --git a/src/lib/film.h b/src/lib/film.h
index e8fcb5a45..9f473d711 100644
--- a/src/lib/film.h
+++ b/src/lib/film.h
@@ -131,7 +131,7 @@ public:
 		) const;
 
 	std::list<ScreenKDM> make_kdms (
-		std::list<boost::shared_ptr<Screen> >,
+		std::list<boost::shared_ptr<Screen> > screens,
 		boost::filesystem::path cpl_file,
 		boost::posix_time::ptime from,
 		boost::posix_time::ptime until,
@@ -160,9 +160,6 @@ public:
 	std::list<DCPTimePeriod> reels () const;
 	std::list<int> mapped_audio_channels () const;
 
-	/** @param A period within the DCP
-	 *  @return Name of the content which most contributes to the given period.
-	 */
 	std::string content_summary (DCPTimePeriod period) const;
 
 	std::list<std::string> fix_conflicting_settings ();
diff --git a/src/lib/filter.h b/src/lib/filter.h
index 36e4dfa27..455b271a2 100644
--- a/src/lib/filter.h
+++ b/src/lib/filter.h
@@ -39,7 +39,7 @@
 class Filter : public boost::noncopyable
 {
 public:
-	Filter (std::string, std::string, std::string, std::string);
+	Filter (std::string i, std::string n, std::string c, std::string f);
 
 	/** @return our id */
 	std::string id () const {
@@ -61,9 +61,9 @@ public:
 	}
 
 	static std::vector<Filter const *> all ();
-	static Filter const * from_id (std::string);
+	static Filter const * from_id (std::string d);
 	static void setup_filters ();
-	static std::string ffmpeg_string (std::vector<Filter const *> const &);
+	static std::string ffmpeg_string (std::vector<Filter const *> const & filters);
 
 private:
 
diff --git a/src/lib/filter_graph.cc b/src/lib/filter_graph.cc
index 7a2973815..2fb1ad187 100644
--- a/src/lib/filter_graph.cc
+++ b/src/lib/filter_graph.cc
@@ -47,11 +47,7 @@ using boost::shared_ptr;
 using boost::weak_ptr;
 using dcp::Size;
 
-/** Construct a FilterGraph for the settings in a piece of content.
- *  @param content Content.
- *  @param s Size of the images to process.
- *  @param p Pixel format of the images to process.
- */
+/** Construct a FilterGraph for the settings in a piece of content */
 FilterGraph::FilterGraph ()
 	: _graph (0)
 	, _copy (false)
diff --git a/src/lib/image.cc b/src/lib/image.cc
index 13ef0db19..8718223ae 100644
--- a/src/lib/image.cc
+++ b/src/lib/image.cc
@@ -103,6 +103,12 @@ Image::planes () const
 }
 
 /** Crop this image, scale it to `inter_size' and then place it in a black frame of `out_size'.
+ *  @param crop Amount to crop by.
+ *  @param inter_size Size to scale the cropped image to.
+ *  @param out_size Size of output frame; if this is larger than inter_size there will be black padding.
+ *  @param yuv_to_rgb YUV to RGB transformation to use, if required.
+ *  @param out_format Output pixel format.
+ *  @param out_aligned true to make the output image aligned.
  *  @param fast Try to be fast at the possible expense of quality; at present this means using
  *  fast bilinear rather than bicubic scaling.
  */
@@ -208,7 +214,11 @@ Image::crop_scale_window (
 	return out;
 }
 
-/** @param fast Try to be fast at the possible expense of quality; at present this means using
+/** @param out_size Size to scale to.
+ *  @param yuv_to_rgb YUVToRGB transform transform to use, if required.
+ *  @param out_format Output pixel format.
+ *  @param out_aligned true to make an aligned output image.
+ *  @param fast Try to be fast at the possible expense of quality; at present this means using
  *  fast bilinear rather than bicubic scaling.
  */
 shared_ptr<Image>
@@ -628,6 +638,7 @@ Image::bytes_per_pixel (int c) const
  *
  *  @param p Pixel format.
  *  @param s Size in pixels.
+ *  @param aligned true to make each row of this image aligned to a 32-byte boundary.
  *  @param extra_pixels Amount of extra "run-off" memory to allocate at the end of each plane in pixels.
  */
 Image::Image (AVPixelFormat p, dcp::Size s, bool aligned, int extra_pixels)
diff --git a/src/lib/image.h b/src/lib/image.h
index c5fc3dd2d..84871aae2 100644
--- a/src/lib/image.h
+++ b/src/lib/image.h
@@ -40,7 +40,7 @@ class Socket;
 class Image
 {
 public:
-	Image (AVPixelFormat, dcp::Size, bool, int extra_pixels = 0);
+	Image (AVPixelFormat p, dcp::Size s, bool aligned, int extra_pixels = 0);
 	Image (AVFrame *);
 	Image (Image const &);
 	Image (boost::shared_ptr<const Image>, bool);
@@ -57,10 +57,10 @@ public:
 	int line_factor (int) const;
 	dcp::Size sample_size (int) const;
 
-	boost::shared_ptr<Image> scale (dcp::Size, dcp::YUVToRGB yuv_to_rgb, AVPixelFormat, bool aligned, bool fast) const;
+	boost::shared_ptr<Image> scale (dcp::Size out_size, dcp::YUVToRGB yuv_to_rgb, AVPixelFormat out_format, bool aligned, bool fast) const;
 	boost::shared_ptr<Image> crop_scale_window (
-		Crop c, dcp::Size, dcp::Size, dcp::YUVToRGB yuv_to_rgb, AVPixelFormat, bool aligned, bool fast)
-		const;
+		Crop crop, dcp::Size inter_size, dcp::Size out_size, dcp::YUVToRGB yuv_to_rgb, AVPixelFormat out_format, bool aligned, bool fast
+		) const;
 
 	void make_black ();
 	void make_transparent ();
diff --git a/src/lib/job.cc b/src/lib/job.cc
index dacc8bf31..31f336b65 100644
--- a/src/lib/job.cc
+++ b/src/lib/job.cc
@@ -302,6 +302,7 @@ Job::check_for_interruption_or_pause ()
 
 /** Set the progress of the current part of the job.
  *  @param p Progress (from 0 to 1)
+ *  @param force Do not ignore this update, even if it hasn't been long since the last one.
  */
 void
 Job::set_progress (float p, bool force)
@@ -374,7 +375,8 @@ Job::error_summary () const
 }
 
 /** Set the current error string.
- *  @param e New error string.
+ *  @param s New error string.
+ *  @param d New error detail string.
  */
 void
 Job::set_error (string s, string d)
diff --git a/src/lib/job.h b/src/lib/job.h
index 311f9cc91..185273e2d 100644
--- a/src/lib/job.h
+++ b/src/lib/job.h
@@ -40,7 +40,7 @@ class Film;
 class Job : public boost::enable_shared_from_this<Job>, public Signaller, public boost::noncopyable
 {
 public:
-	Job (boost::shared_ptr<const Film>);
+	Job (boost::shared_ptr<const Film> film);
 	virtual ~Job ();
 
 	/** @return user-readable name of this job */
diff --git a/src/lib/player_video.cc b/src/lib/player_video.cc
index b7fb52e3a..2e53a6aa6 100644
--- a/src/lib/player_video.cc
+++ b/src/lib/player_video.cc
@@ -99,6 +99,8 @@ PlayerVideo::set_subtitle (PositionImage image)
  *  @param pixel_format Function which is called to decide what pixel format the output image should be;
  *  it is passed the pixel format of the input image from the ImageProxy, and should return the desired
  *  output pixel format.  Two functions always_rgb and keep_xyz_or_rgb are provided for use here.
+ *  @param aligned true if the output image should be aligned to 32-byte boundaries.
+ *  @param fast true to be fast at the expense of quality.
  */
 shared_ptr<Image>
 PlayerVideo::image (dcp::NoteHandler note, function<AVPixelFormat (AVPixelFormat)> pixel_format, bool aligned, bool fast) const
diff --git a/src/lib/playlist.cc b/src/lib/playlist.cc
index 6abbbcab3..aa365ead4 100644
--- a/src/lib/playlist.cc
+++ b/src/lib/playlist.cc
@@ -159,7 +159,11 @@ Playlist::video_identifier () const
 	return digester.get ();
 }
 
-/** @param node <Playlist> node */
+/** @param film Film that this Playlist is for.
+ *  @param node &lt;Playlist&gt; node.
+ *  @param version Metadata version number.
+ *  @param notes Output notes about that happened.
+ */
 void
 Playlist::set_from_xml (shared_ptr<const Film> film, cxml::ConstNodePtr node, int version, list<string>& notes)
 {
@@ -173,7 +177,9 @@ Playlist::set_from_xml (shared_ptr<const Film> film, cxml::ConstNodePtr node, in
 	reconnect ();
 }
 
-/** @param node <Playlist> node */
+/** @param node &lt;Playlist&gt; node.
+ *  @param with_content_paths true to include &lt;Path&gt; nodes in &lt;Content&gt; nodes, false to omit them.
+ */
 void
 Playlist::as_xml (xmlpp::Node* node, bool with_content_paths)
 {
diff --git a/src/lib/playlist.h b/src/lib/playlist.h
index 335e26013..0b19a6e44 100644
--- a/src/lib/playlist.h
+++ b/src/lib/playlist.h
@@ -46,7 +46,7 @@ public:
 	~Playlist ();
 
 	void as_xml (xmlpp::Node *, bool with_content_paths);
-	void set_from_xml (boost::shared_ptr<const Film>, cxml::ConstNodePtr, int, std::list<std::string> &);
+	void set_from_xml (boost::shared_ptr<const Film> film, cxml::ConstNodePtr node, int version, std::list<std::string>& notes);
 
 	void add (boost::shared_ptr<Content>);
 	void remove (boost::shared_ptr<Content>);
diff --git a/src/lib/scoped_temporary.cc b/src/lib/scoped_temporary.cc
index 3503808bc..5c885e4df 100644
--- a/src/lib/scoped_temporary.cc
+++ b/src/lib/scoped_temporary.cc
@@ -21,7 +21,7 @@
 #include "scoped_temporary.h"
 
 /** Construct a ScopedTemporary.  A temporary filename is decided but the file is not opened
- *  until ::open() is called.
+ *  until open() is called.
  */
 ScopedTemporary::ScopedTemporary ()
 	: _open (0)
diff --git a/src/lib/send_kdm_email_job.cc b/src/lib/send_kdm_email_job.cc
index 642939462..890115747 100644
--- a/src/lib/send_kdm_email_job.cc
+++ b/src/lib/send_kdm_email_job.cc
@@ -30,7 +30,12 @@ using std::string;
 using std::list;
 using boost::shared_ptr;
 
-/** @param log Log to write to, or 0 */
+/** @param cinema_kdms KDMs to email.
+ *  @param name_format Format to use for filenames.
+ *  @param name_values Values to substitute into the filenames.
+ *  @param cpl_name Name of the CPL that the KDMs are for.
+ *  @param log Log to write to, or 0.
+ */
 SendKDMEmailJob::SendKDMEmailJob (
 	list<CinemaKDMs> cinema_kdms,
 	dcp::NameFormat name_format,
diff --git a/src/lib/send_problem_report_job.cc b/src/lib/send_problem_report_job.cc
index c8b577ca7..aac2b6e66 100644
--- a/src/lib/send_problem_report_job.cc
+++ b/src/lib/send_problem_report_job.cc
@@ -36,7 +36,10 @@ using std::string;
 using std::list;
 using boost::shared_ptr;
 
-/** @param film Film thta the problem is with, or 0 */
+/** @param film Film thta the problem is with, or 0.
+ *  @param from Email address to use for From:
+ *  @param summary Summary of the problem.
+ */
 SendProblemReportJob::SendProblemReportJob (
 	shared_ptr<const Film> film,
 	string from,
diff --git a/src/lib/send_problem_report_job.h b/src/lib/send_problem_report_job.h
index ff787852e..c4371a54e 100644
--- a/src/lib/send_problem_report_job.h
+++ b/src/lib/send_problem_report_job.h
@@ -26,7 +26,7 @@ class SendProblemReportJob : public Job
 {
 public:
 	SendProblemReportJob (
-		boost::shared_ptr<const Film>,
+		boost::shared_ptr<const Film> film,
 		std::string from,
 		std::string summary
 		);
diff --git a/src/lib/subtitle_decoder.h b/src/lib/subtitle_decoder.h
index 2b38153bf..6d0479638 100644
--- a/src/lib/subtitle_decoder.h
+++ b/src/lib/subtitle_decoder.h
@@ -52,8 +52,8 @@ public:
 		return _position;
 	}
 
-	void emit_image (ContentTimePeriod period, boost::shared_ptr<Image>, dcpomatic::Rect<double>);
-	void emit_text (ContentTimePeriod period, std::list<dcp::SubtitleString>);
+	void emit_image (ContentTimePeriod period, boost::shared_ptr<Image> image, dcpomatic::Rect<double> rect);
+	void emit_text (ContentTimePeriod period, std::list<dcp::SubtitleString> s);
 	void emit_text (ContentTimePeriod period, sub::Subtitle const & subtitle);
 
 	boost::shared_ptr<const SubtitleContent> content () const {
diff --git a/src/lib/transcode_job.cc b/src/lib/transcode_job.cc
index 79b5b1739..17108c278 100644
--- a/src/lib/transcode_job.cc
+++ b/src/lib/transcode_job.cc
@@ -44,8 +44,7 @@ using std::setprecision;
 using std::cout;
 using boost::shared_ptr;
 
-/** @param s Film to use.
- */
+/** @param film Film to use */
 TranscodeJob::TranscodeJob (shared_ptr<const Film> film)
 	: Job (film)
 {
diff --git a/src/lib/transcode_job.h b/src/lib/transcode_job.h
index 5419a46f3..14ad693c3 100644
--- a/src/lib/transcode_job.h
+++ b/src/lib/transcode_job.h
@@ -33,7 +33,7 @@ class Transcoder;
 class TranscodeJob : public Job
 {
 public:
-	TranscodeJob (boost::shared_ptr<const Film>);
+	TranscodeJob (boost::shared_ptr<const Film> film);
 
 	std::string name () const;
 	std::string json_name () const;
diff --git a/src/lib/transcoder.cc b/src/lib/transcoder.cc
index de2fb1d33..21ef60b79 100644
--- a/src/lib/transcoder.cc
+++ b/src/lib/transcoder.cc
@@ -51,14 +51,14 @@ using boost::weak_ptr;
 using boost::dynamic_pointer_cast;
 
 /** Construct a transcoder.
- *  @param f Film that we are transcoding.
- *  @param j Job that this transcoder is being used in.
+ *  @param film Film that we are transcoding.
+ *  @param job Job that this transcoder is being used in.
  */
-Transcoder::Transcoder (shared_ptr<const Film> film, weak_ptr<Job> j)
+Transcoder::Transcoder (shared_ptr<const Film> film, weak_ptr<Job> job)
 	: _film (film)
-	, _job (j)
+	, _job (job)
 	, _player (new Player (film, film->playlist ()))
-	, _writer (new Writer (film, j))
+	, _writer (new Writer (film, job))
 	, _encoder (new Encoder (film, _writer))
 	, _finishing (false)
 	, _non_burnt_subtitles (false)
diff --git a/src/lib/transcoder.h b/src/lib/transcoder.h
index 0095ad9d1..50cbfdfec 100644
--- a/src/lib/transcoder.h
+++ b/src/lib/transcoder.h
@@ -34,7 +34,7 @@ class AudioBuffers;
 class Transcoder : public boost::noncopyable
 {
 public:
-	Transcoder (boost::shared_ptr<const Film>, boost::weak_ptr<Job>);
+	Transcoder (boost::shared_ptr<const Film> film, boost::weak_ptr<Job> job);
 
 	void go ();
 
diff --git a/src/lib/util.cc b/src/lib/util.cc
index 38770f4e3..574d1d889 100644
--- a/src/lib/util.cc
+++ b/src/lib/util.cc
@@ -462,7 +462,7 @@ digest_head_tail (vector<boost::filesystem::path> files, boost::uintmax_t size)
 
 /** Round a number up to the nearest multiple of another number.
  *  @param c Index.
- *  @param s Array of numbers to round, indexed by c.
+ *  @param stride Array of numbers to round, indexed by c.
  *  @param t Multiple to round to.
  *  @return Rounded number.
  */
diff --git a/src/lib/writer.h b/src/lib/writer.h
index 14b21f359..2a78637e5 100644
--- a/src/lib/writer.h
+++ b/src/lib/writer.h
@@ -82,7 +82,7 @@ bool operator== (QueueItem const & a, QueueItem const & b);
  *  or AudioBuffers objects (containing image or sound data respectively)
  *  and writes them to the assets.
  *
- *  ::write() for Data (picture) can be called out of order, and the Writer
+ *  write() for Data (picture) can be called out of order, and the Writer
  *  will sort it out.  write() for AudioBuffers must be called in order.
  */
 
diff --git a/src/wx/audio_dialog.cc b/src/wx/audio_dialog.cc
index ebccd53f5..8a38c8a87 100644
--- a/src/wx/audio_dialog.cc
+++ b/src/wx/audio_dialog.cc
@@ -41,7 +41,10 @@ using boost::optional;
 using boost::const_pointer_cast;
 using boost::dynamic_pointer_cast;
 
-/** @param content Content to analyse, or 0 to analyse all of the film's audio */
+/** @param parent Parent window.
+ *  @param film Film we are using.
+ *  @param content Content to analyse, or 0 to analyse all of the film's audio.
+ */
 AudioDialog::AudioDialog (wxWindow* parent, shared_ptr<Film> film, shared_ptr<Content> content)
 	: wxDialog (
 		parent,
diff --git a/src/wx/audio_dialog.h b/src/wx/audio_dialog.h
index 37d425624..41be90b79 100644
--- a/src/wx/audio_dialog.h
+++ b/src/wx/audio_dialog.h
@@ -31,7 +31,7 @@ class Film;
 class AudioDialog : public wxDialog
 {
 public:
-	AudioDialog (wxWindow *, boost::shared_ptr<Film> film, boost::shared_ptr<Content> content = boost::shared_ptr<Content> ());
+	AudioDialog (wxWindow* parent, boost::shared_ptr<Film> film, boost::shared_ptr<Content> content = boost::shared_ptr<Content> ());
 
 	bool Show (bool show = true);
 
diff --git a/src/wx/content_widget.h b/src/wx/content_widget.h
index 744d0a7a2..e162aca49 100644
--- a/src/wx/content_widget.h
+++ b/src/wx/content_widget.h
@@ -49,8 +49,11 @@ public:
 	/** @param parent Parent window.
 	 *  @param wrapped Control widget that we are wrapping.
 	 *  @param property ContentProperty that the widget is handling.
+	 *  @param part Part of Content that the property is in (e.g. &Content::video)
 	 *  @param model_getter Function on the Content to get the value.
 	 *  @param model_setter Function on the Content to set the value.
+	 *  @param view_to_model Function to convert a view value to a model value.
+	 *  @param model_to_view Function to convert a model value to a view value.
 	 */
 	ContentWidget (
 		wxWindow* parent,
diff --git a/src/wx/film_editor.cc b/src/wx/film_editor.cc
index edf5d3bd7..7dd7e4ef3 100644
--- a/src/wx/film_editor.cc
+++ b/src/wx/film_editor.cc
@@ -41,7 +41,6 @@ using std::list;
 using boost::shared_ptr;
 using boost::optional;
 
-/** @param f Film to edit */
 FilmEditor::FilmEditor (wxWindow* parent, FilmViewer* viewer)
 	: wxPanel (parent)
 {
diff --git a/src/wx/isdcf_metadata_dialog.cc b/src/wx/isdcf_metadata_dialog.cc
index bef0851e0..ee7d4ae70 100644
--- a/src/wx/isdcf_metadata_dialog.cc
+++ b/src/wx/isdcf_metadata_dialog.cc
@@ -27,7 +27,10 @@
 
 using boost::shared_ptr;
 
-/** @param threed true if the film is in 3D */
+/** @param parent Parent window.
+ *  @param dm Initial ISDCF metadata.
+ *  @param threed true if the film is in 3D.
+ */
 ISDCFMetadataDialog::ISDCFMetadataDialog (wxWindow* parent, ISDCFMetadata dm, bool threed)
 	: TableDialog (parent, _("ISDCF name"), 2, 1, true)
 {
diff --git a/src/wx/report_problem_dialog.cc b/src/wx/report_problem_dialog.cc
index 7519259eb..77540fcbc 100644
--- a/src/wx/report_problem_dialog.cc
+++ b/src/wx/report_problem_dialog.cc
@@ -28,7 +28,9 @@
 using std::string;
 using boost::shared_ptr;
 
-/** @param film Film that we are working on, or 0 */
+/** @param parent Parent window.
+ *  @param film Film that we are working on, or 0.
+ */
 ReportProblemDialog::ReportProblemDialog (wxWindow* parent, shared_ptr<Film> film)
 	: wxDialog (parent, wxID_ANY, _("Report A Problem"))
 	, _film (film)
diff --git a/src/wx/report_problem_dialog.h b/src/wx/report_problem_dialog.h
index fda3761d3..a13c6a671 100644
--- a/src/wx/report_problem_dialog.h
+++ b/src/wx/report_problem_dialog.h
@@ -29,7 +29,7 @@ class Film;
 class ReportProblemDialog : public wxDialog
 {
 public:
-	ReportProblemDialog (wxWindow* parent, boost::shared_ptr<Film>);
+	ReportProblemDialog (wxWindow* parent, boost::shared_ptr<Film> film);
 
 	void report ();
 
@@ -42,4 +42,3 @@ private:
 	wxCheckBox* _send_logs;
 	wxTextCtrl* _email;
 };
-
diff --git a/src/wx/system_font_dialog.h b/src/wx/system_font_dialog.h
index 35ed0827e..9cced4956 100644
--- a/src/wx/system_font_dialog.h
+++ b/src/wx/system_font_dialog.h
@@ -22,7 +22,7 @@
  *  @brief A dialog box to select one of the "system" fonts on Windows.
  *
  *  This is necessary because wxFileDialog on Windows will not display
- *  the contents of c:\Windows\Fonts, so we need a different way to choose
+ *  the contents of `c:\Windows\Fonts`, so we need a different way to choose
  *  one of those fonts.
  */
 
diff --git a/test/4k_test.cc b/test/4k_test.cc
index 033796ab2..e6e2cc7ce 100644
--- a/test/4k_test.cc
+++ b/test/4k_test.cc
@@ -18,8 +18,11 @@
 
 */
 
+/** @defgroup completedcp Complete builds of DCPs with various characteristics, testing broad areas of code */
+
 /** @file  test/4k_test.cc
  *  @brief Run a 4K encode from a simple input.
+ *  @ingroup completedcp
  *
  *  The output is checked against test/data/4k_test.
  */
diff --git a/test/audio_delay_test.cc b/test/audio_delay_test.cc
index 1d2d171db..db64bc7c8 100644
--- a/test/audio_delay_test.cc
+++ b/test/audio_delay_test.cc
@@ -18,8 +18,11 @@
 
 */
 
+/** @defgroup specific Tests of fairly specific areas */
+
 /** @file  test/audio_delay_test.cc
  *  @brief Test encode using some FFmpegContents which have audio delays.
+ *  @ingroup specific
  *
  *  The output is checked algorithmically using knowledge of the input.
  */
diff --git a/test/audio_processor_delay_test.cc b/test/audio_processor_delay_test.cc
index 78f8e6895..bb0538661 100644
--- a/test/audio_processor_delay_test.cc
+++ b/test/audio_processor_delay_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/audio_processor_delay_test.cc
+ *  @brief Test the AudioDelay class.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/audio_delay.h"
 #include "lib/audio_buffers.h"
 #include <boost/test/unit_test.hpp>
diff --git a/test/audio_processor_test.cc b/test/audio_processor_test.cc
index 82ae9e563..e3917af42 100644
--- a/test/audio_processor_test.cc
+++ b/test/audio_processor_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/audio_processor_test.cc
+ *  @brief Test audio processors.
+ *  @ingroup specific
+ */
+
 #include "lib/audio_processor.h"
 #include "lib/analyse_audio_job.h"
 #include "lib/dcp_content_type.h"
diff --git a/test/burnt_subtitle_test.cc b/test/burnt_subtitle_test.cc
index e8c3f3597..054eddb31 100644
--- a/test/burnt_subtitle_test.cc
+++ b/test/burnt_subtitle_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/burnt_subtitle_test.cc
  *  @brief Test the burning of subtitles into the DCP.
+ *  @ingroup specific
  */
 
 #include "lib/text_subtitle_content.h"
diff --git a/test/client_server_test.cc b/test/client_server_test.cc
index e21f41c79..fab9411ab 100644
--- a/test/client_server_test.cc
+++ b/test/client_server_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/client_server_test.cc
  *  @brief Test the server class.
+ *  @ingroup specific
  *
  *  Create a test image and then encode it using the standard mechanism
  *  and also using a EncodeServer object running on localhost.  Compare the resulting
diff --git a/test/dcp_subtitle_test.cc b/test/dcp_subtitle_test.cc
index b1689a6cc..92a415ae1 100644
--- a/test/dcp_subtitle_test.cc
+++ b/test/dcp_subtitle_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/dcp_subtitle_test.cc
  *  @brief Test DCP subtitle content in various ways.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/dcpomatic_time_test.cc b/test/dcpomatic_time_test.cc
index 7489e7a24..f49d29a57 100644
--- a/test/dcpomatic_time_test.cc
+++ b/test/dcpomatic_time_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/dcpomatic_time_test.cc
+ *  @brief Test Time and TimePeriod classes.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/dcpomatic_time.h"
 #include <boost/test/unit_test.hpp>
 #include <list>
diff --git a/test/digest_test.cc b/test/digest_test.cc
index 7395fe468..b96cb7ad7 100644
--- a/test/digest_test.cc
+++ b/test/digest_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/digest_test.cc
+ *  @brief Check computed DCP digests against references calculated by the `openssl` binary.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/image_content.h"
 #include "lib/dcp_content_type.h"
diff --git a/test/ffmpeg_audio_only_test.cc b/test/ffmpeg_audio_only_test.cc
index a7e2ca025..716cf5055 100644
--- a/test/ffmpeg_audio_only_test.cc
+++ b/test/ffmpeg_audio_only_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/ffmpeg_audio_only_test.cc
+ *  @brief Test FFmpeg content with audio but no video.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/ffmpeg_content.h"
 #include "lib/dcp_content_type.h"
diff --git a/test/ffmpeg_audio_test.cc b/test/ffmpeg_audio_test.cc
index 1e9048584..ec5752b9d 100644
--- a/test/ffmpeg_audio_test.cc
+++ b/test/ffmpeg_audio_test.cc
@@ -19,7 +19,8 @@
 */
 
 /** @file  test/ffmpeg_audio_test.cc
- *  @brief A simple test of reading audio from an FFmpeg file.
+ *  @brief Test reading audio from an FFmpeg file.
+ *  @ingroup specific
  */
 
 #include "lib/ffmpeg_content.h"
diff --git a/test/ffmpeg_dcp_test.cc b/test/ffmpeg_dcp_test.cc
index 748695efe..7cdecb22f 100644
--- a/test/ffmpeg_dcp_test.cc
+++ b/test/ffmpeg_dcp_test.cc
@@ -20,6 +20,7 @@
 
 /** @file test/ffmpeg_dcp_test.cc
  *  @brief Test creation of a very simple DCP from some FFmpegContent (data/test.mp4).
+ *  @ingroup specific
  *
  *  Also a quick test of Film::have_dcp ().
  */
diff --git a/test/ffmpeg_decoder_seek_test.cc b/test/ffmpeg_decoder_seek_test.cc
index 46d82b022..26fab5f3d 100644
--- a/test/ffmpeg_decoder_seek_test.cc
+++ b/test/ffmpeg_decoder_seek_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/ffmpeg_decoder_seek_test.cc
  *  @brief Check seek() with FFmpegDecoder.
+ *  @ingroup specific
  *
  *  This doesn't check that the contents of those frames are right, which
  *  it probably should.
diff --git a/test/ffmpeg_decoder_sequential_test.cc b/test/ffmpeg_decoder_sequential_test.cc
index 2fec7a37e..6bda8f260 100644
--- a/test/ffmpeg_decoder_sequential_test.cc
+++ b/test/ffmpeg_decoder_sequential_test.cc
@@ -21,6 +21,7 @@
 /** @file  test/ffmpeg_decoder_sequential_test.cc
  *  @brief Check that the FFmpeg decoder and Player produce sequential frames without gaps or dropped frames;
  *  Also that the decoder picks up frame rates correctly.
+ *  @ingroup specific
  */
 
 #include "lib/ffmpeg_content.h"
diff --git a/test/ffmpeg_examiner_test.cc b/test/ffmpeg_examiner_test.cc
index 411316089..0233db1f0 100644
--- a/test/ffmpeg_examiner_test.cc
+++ b/test/ffmpeg_examiner_test.cc
@@ -21,6 +21,7 @@
 /** @file  test/ffmpeg_examiner_test.cc
  *  @brief Check that the FFmpegExaminer can extract the first video and audio time
  *  correctly from data/count300bd24.m2ts.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/ffmpeg_pts_offset_test.cc b/test/ffmpeg_pts_offset_test.cc
index f9371f74c..85a1e7844 100644
--- a/test/ffmpeg_pts_offset_test.cc
+++ b/test/ffmpeg_pts_offset_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/ffmpeg_pts_offset_test.cc
  *  @brief Check the computation of _pts_offset in FFmpegDecoder.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/file_log_test.cc b/test/file_log_test.cc
index d7fe027d8..e0eeba010 100644
--- a/test/file_log_test.cc
+++ b/test/file_log_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/file_log_test.cc
+ *  @brief Test FileLog.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/file_log.h"
 #include <boost/test/unit_test.hpp>
 #include <iostream>
diff --git a/test/file_naming_test.cc b/test/file_naming_test.cc
index f4235dec2..8951f8380 100644
--- a/test/file_naming_test.cc
+++ b/test/file_naming_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/file_naming_test.cc
+ *  @brief Test how files in DCPs are named.
+ *  @ingroup specific
+ */
+
 #include "test.h"
 #include "lib/config.h"
 #include "lib/film.h"
diff --git a/test/film_metadata_test.cc b/test/film_metadata_test.cc
index 4dfd6f2a5..3fd4ba9d1 100644
--- a/test/film_metadata_test.cc
+++ b/test/film_metadata_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/film_metadata_test.cc
  *  @brief Test some basic reading/writing of film metadata.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/frame_rate_test.cc b/test/frame_rate_test.cc
index 592b7af8b..9521e3909 100644
--- a/test/frame_rate_test.cc
+++ b/test/frame_rate_test.cc
@@ -21,6 +21,7 @@
 /** @file  test/frame_rate_test.cc
  *  @brief Tests for FrameRateChange and the computation of the best
  *  frame rate for the DCP.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/image_filename_sorter_test.cc b/test/image_filename_sorter_test.cc
index 69f8c9ff1..113c24d10 100644
--- a/test/image_filename_sorter_test.cc
+++ b/test/image_filename_sorter_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/image_filename_sorter_test.cc
+ *  @brief Test ImageFilenameSorter
+ *  @ingroup selfcontained
+ */
+
 #include "lib/image_filename_sorter.h"
 #include <boost/test/unit_test.hpp>
 
diff --git a/test/import_dcp_test.cc b/test/import_dcp_test.cc
index cd0396d07..163a3a4a9 100644
--- a/test/import_dcp_test.cc
+++ b/test/import_dcp_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/import_dcp_test.cc
+ *  @brief Test import of encrypted DCPs.
+ *  @ingroup specific
+ */
+
 #include "test.h"
 #include "lib/film.h"
 #include "lib/dcp_subtitle_content.h"
diff --git a/test/interrupt_encoder_test.cc b/test/interrupt_encoder_test.cc
index 8883c2d6f..1068ed5b2 100644
--- a/test/interrupt_encoder_test.cc
+++ b/test/interrupt_encoder_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/interrupt_encoder_test.cc
+ *  @brief Test clean shutdown of threads if a DCP encode is interrupted.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/dcp_content_type.h"
 #include "lib/ratio.h"
diff --git a/test/isdcf_name_test.cc b/test/isdcf_name_test.cc
index bb47fa9c0..cc224aab7 100644
--- a/test/isdcf_name_test.cc
+++ b/test/isdcf_name_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/isdcf_name_test.cc
+ *  @brief Test creation of ISDCF names.
+ *  @ingroup specific
+ */
+
 #include <boost/test/unit_test.hpp>
 #include "lib/film.h"
 #include "lib/ratio.h"
diff --git a/test/j2k_bandwidth_test.cc b/test/j2k_bandwidth_test.cc
index ed8f5d9c8..a941b4ae6 100644
--- a/test/j2k_bandwidth_test.cc
+++ b/test/j2k_bandwidth_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/j2k_bandwidth_test.cc
+ *  @brief Test whether we output whatever J2K bandwidth is requested.
+ *  @ingroup specific
+ */
+
 #include "test.h"
 #include "lib/dcp_content_type.h"
 #include "lib/film.h"
diff --git a/test/recover_test.cc b/test/recover_test.cc
index 93288c300..95e45e08b 100644
--- a/test/recover_test.cc
+++ b/test/recover_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/recover_test.cc
  *  @brief Test recovery of a DCP transcode after a crash.
+ *  @ingroup specific
  */
 
 #include "test.h"
diff --git a/test/rect_test.cc b/test/rect_test.cc
index 90d6f096f..1e3730148 100644
--- a/test/rect_test.cc
+++ b/test/rect_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/rect_test.cc
+ *  @brief Test Rect class.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/rect.h"
 #include <boost/test/unit_test.hpp>
 #include <iostream>
diff --git a/test/reels_test.cc b/test/reels_test.cc
index 1951d5374..a9ed07e73 100644
--- a/test/reels_test.cc
+++ b/test/reels_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/reels_test.cc
+ *  @brief Check manipulation of reels in various ways.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/ratio.h"
 #include "lib/ffmpeg_content.h"
diff --git a/test/render_subtitles_test.cc b/test/render_subtitles_test.cc
index 79c0e782b..4276a2b01 100644
--- a/test/render_subtitles_test.cc
+++ b/test/render_subtitles_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/render_subtitles_test.cc
+ *  @brief Check markup of subtitles for rendering.
+ *  @ingroup specific
+ */
+
 #include "lib/render_subtitles.h"
 #include <dcp/subtitle_string.h>
 #include <boost/test/unit_test.hpp>
diff --git a/test/repeat_frame_test.cc b/test/repeat_frame_test.cc
index 7eac4e1a8..3ca9a738a 100644
--- a/test/repeat_frame_test.cc
+++ b/test/repeat_frame_test.cc
@@ -21,6 +21,7 @@
 /** @file  test/repeat_frame_test.cc
  *  @brief Test the repeat of frames by the player when putting a 24fps
  *  source into a 48fps DCP.
+ *  @ingroup specific
  *
  *  @see test/skip_frame_test.cc
  */
diff --git a/test/required_disk_space_test.cc b/test/required_disk_space_test.cc
index a34604dd4..bcb53bdaf 100644
--- a/test/required_disk_space_test.cc
+++ b/test/required_disk_space_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/required_disk_space_test.cc
+ *  @brief Check Film::required_disk_space
+ *  @ingroup specific
+ */
+
 #include "lib/content_factory.h"
 #include "lib/film.h"
 #include "lib/dcp_content.h"
diff --git a/test/scaling_test.cc b/test/scaling_test.cc
index 5ac5c7525..13276977d 100644
--- a/test/scaling_test.cc
+++ b/test/scaling_test.cc
@@ -20,6 +20,7 @@
 
 /** @file test/scaling_test.cc
  *  @brief Test scaling and black-padding of images from a still-image source.
+ *  @ingroup specific
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/silence_padding_test.cc b/test/silence_padding_test.cc
index 1eb502007..6c7d0b5ff 100644
--- a/test/silence_padding_test.cc
+++ b/test/silence_padding_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/silence_padding_test.cc
  *  @brief Test the padding (with silence) of a mono source to a 6-channel DCP.
+ *  @ingroup specific
  */
 
 #include "lib/ffmpeg_content.h"
diff --git a/test/skip_frame_test.cc b/test/skip_frame_test.cc
index 535efacdf..97aadb2f7 100644
--- a/test/skip_frame_test.cc
+++ b/test/skip_frame_test.cc
@@ -21,6 +21,7 @@
 /** @file  test/skip_frame_test.cc
  *  @brief Test the skip of frames by the player when putting a 48fps
  *  source into a 24fps DCP.
+ *  @ingroup specific
  *
  *  @see test/repeat_frame_test.cc
  */
diff --git a/test/srt_subtitle_test.cc b/test/srt_subtitle_test.cc
index ecf2130ec..9b9e6b5c6 100644
--- a/test/srt_subtitle_test.cc
+++ b/test/srt_subtitle_test.cc
@@ -20,6 +20,7 @@
 
 /** @file  test/srt_subtitle_test.cc
  *  @brief Test writing DCPs with subtitles from .srt.
+ *  @ingroup specific
  */
 
 #include "lib/film.h"
diff --git a/test/ssa_subtitle_test.cc b/test/ssa_subtitle_test.cc
index ed8c20424..63a90b448 100644
--- a/test/ssa_subtitle_test.cc
+++ b/test/ssa_subtitle_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/ssa_subtitle_test.cc
+ *  @brief Test use of SSA subtitle files.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/text_subtitle_content.h"
 #include "lib/dcp_content_type.h"
diff --git a/test/threed_test.cc b/test/threed_test.cc
index 4ffbdf0e6..30de1f1a2 100644
--- a/test/threed_test.cc
+++ b/test/threed_test.cc
@@ -19,7 +19,8 @@
 */
 
 /** @file  test/threed_test.cc
- *  @brief Create a 3D DCP (without comparing the result to anything).
+ *  @brief Create some 3D DCPs (without comparing the results to anything).
+ *  @ingroup completedcp
  */
 
 #include <boost/test/unit_test.hpp>
diff --git a/test/time_calculation_test.cc b/test/time_calculation_test.cc
index 391d30dbd..4524242d9 100644
--- a/test/time_calculation_test.cc
+++ b/test/time_calculation_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/time_calculation_test.cc
+ *  @brief Test calculation of timings when frame rates change.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/ffmpeg_content.h"
 #include "lib/video_content.h"
diff --git a/test/torture_test.cc b/test/torture_test.cc
index b941a5ade..958e7167d 100644
--- a/test/torture_test.cc
+++ b/test/torture_test.cc
@@ -19,7 +19,8 @@
 */
 
 /** @file  test/torture_test.cc
- *  @brief Entire projects that are programmatically created and checked.
+ *  @brief Tricky arrangements of content whose resulting DCPs are checked programmatically.
+ *  @ingroup completedcp
  */
 
 #include "lib/audio_content.h"
diff --git a/test/update_checker_test.cc b/test/update_checker_test.cc
index 621b0572e..772665772 100644
--- a/test/update_checker_test.cc
+++ b/test/update_checker_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/update_checker_test.cc
+ *  @brief Check UpdateChecker::version_less_than
+ *  @ingroup specific
+ */
+
 #include <boost/test/unit_test.hpp>
 #include "lib/update_checker.h"
 
diff --git a/test/upmixer_a_test.cc b/test/upmixer_a_test.cc
index 99c897252..2dccedacb 100644
--- a/test/upmixer_a_test.cc
+++ b/test/upmixer_a_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/upmixer_a_test.cc
+ *  @brief Check the Upmixer A against some reference sound files.
+ *  @ingroup specific
+ */
+
 #include <boost/test/unit_test.hpp>
 #include <sndfile.h>
 #include "lib/film.h"
diff --git a/test/vf_kdm_test.cc b/test/vf_kdm_test.cc
index c7b0669c9..981ed43d4 100644
--- a/test/vf_kdm_test.cc
+++ b/test/vf_kdm_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/vf_kdm_test.cc
+ *  @brief Test encrypted VF creation and import
+ *  @ingroup specific
+ */
+
 #include "test.h"
 #include "lib/film.h"
 #include "lib/dcp_subtitle_content.h"
diff --git a/test/vf_test.cc b/test/vf_test.cc
index 80d167ee2..ac8256be3 100644
--- a/test/vf_test.cc
+++ b/test/vf_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/vf_Test.cc
+ *  @brief Various VF-related tests.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/dcp_content.h"
 #include "lib/ffmpeg_content.h"
diff --git a/test/video_content_scale_test.cc b/test/video_content_scale_test.cc
index e7fddd720..202243dd8 100644
--- a/test/video_content_scale_test.cc
+++ b/test/video_content_scale_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/video_content_scale_test.cc
+ *  @brief Test VideoContentScale
+ *  @ingroup selfcontained
+ */
+
 #include "lib/ffmpeg_content.h"
 #include "lib/ratio.h"
 #include "lib/video_content.h"
diff --git a/test/video_mxf_content_test.cc b/test/video_mxf_content_test.cc
index bdd35713c..9104702b6 100644
--- a/test/video_mxf_content_test.cc
+++ b/test/video_mxf_content_test.cc
@@ -18,6 +18,11 @@
 
 */
 
+/** @file  test/video_mxf_content_test.cc
+ *  @brief Test use of Video MXF content.
+ *  @ingroup specific
+ */
+
 #include "lib/film.h"
 #include "lib/video_mxf_content.h"
 #include "lib/content_factory.h"