Various Doxygen fixes.
authorCarl Hetherington <cth@carlh.net>
Thu, 2 Mar 2017 15:37:13 +0000 (15:37 +0000)
committerCarl Hetherington <cth@carlh.net>
Wed, 19 Apr 2017 22:04:32 +0000 (23:04 +0100)
91 files changed:
Doxyfile
doc/mainpage.txt
src/lib/audio_buffers.cc
src/lib/audio_buffers.h
src/lib/cinema_kdms.cc
src/lib/config.h
src/lib/content.h
src/lib/cross.h
src/lib/dcp_video.cc
src/lib/dcpomatic_socket.cc
src/lib/dcpomatic_time.h
src/lib/encoder.cc
src/lib/encoder.h
src/lib/exceptions.h
src/lib/ffmpeg_subtitle_stream.cc
src/lib/ffmpeg_subtitle_stream.h
src/lib/film.cc
src/lib/film.h
src/lib/filter.h
src/lib/filter_graph.cc
src/lib/image.cc
src/lib/image.h
src/lib/job.cc
src/lib/job.h
src/lib/player_video.cc
src/lib/playlist.cc
src/lib/playlist.h
src/lib/scoped_temporary.cc
src/lib/send_kdm_email_job.cc
src/lib/send_problem_report_job.cc
src/lib/send_problem_report_job.h
src/lib/subtitle_decoder.h
src/lib/transcode_job.cc
src/lib/transcode_job.h
src/lib/transcoder.cc
src/lib/transcoder.h
src/lib/util.cc
src/lib/writer.h
src/wx/audio_dialog.cc
src/wx/audio_dialog.h
src/wx/content_widget.h
src/wx/film_editor.cc
src/wx/isdcf_metadata_dialog.cc
src/wx/report_problem_dialog.cc
src/wx/report_problem_dialog.h
src/wx/system_font_dialog.h
test/4k_test.cc
test/audio_delay_test.cc
test/audio_processor_delay_test.cc
test/audio_processor_test.cc
test/burnt_subtitle_test.cc
test/client_server_test.cc
test/dcp_subtitle_test.cc
test/dcpomatic_time_test.cc
test/digest_test.cc
test/ffmpeg_audio_only_test.cc
test/ffmpeg_audio_test.cc
test/ffmpeg_dcp_test.cc
test/ffmpeg_decoder_seek_test.cc
test/ffmpeg_decoder_sequential_test.cc
test/ffmpeg_examiner_test.cc
test/ffmpeg_pts_offset_test.cc
test/file_log_test.cc
test/file_naming_test.cc
test/film_metadata_test.cc
test/frame_rate_test.cc
test/image_filename_sorter_test.cc
test/import_dcp_test.cc
test/interrupt_encoder_test.cc
test/isdcf_name_test.cc
test/j2k_bandwidth_test.cc
test/recover_test.cc
test/rect_test.cc
test/reels_test.cc
test/render_subtitles_test.cc
test/repeat_frame_test.cc
test/required_disk_space_test.cc
test/scaling_test.cc
test/silence_padding_test.cc
test/skip_frame_test.cc
test/srt_subtitle_test.cc
test/ssa_subtitle_test.cc
test/threed_test.cc
test/time_calculation_test.cc
test/torture_test.cc
test/update_checker_test.cc
test/upmixer_a_test.cc
test/vf_kdm_test.cc
test/vf_test.cc
test/video_content_scale_test.cc
test/video_mxf_content_test.cc

index e9b6827..dd89069 100644 (file)
--- 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
index 20d962c..81f8a6e 100644 (file)
@@ -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`   | &lsquo;backend&rsquo; 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/
  */
index aea581a..825c6c2 100644 (file)
@@ -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
index 991ef53..f4a0c1f 100644 (file)
@@ -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
index 8cac65f..605e414 100644 (file)
@@ -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
index 80dfb1d..ed29a8f 100644 (file)
@@ -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;
index 519ff89..334a827 100644 (file)
@@ -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);
index c7bb499..9fac7e6 100644 (file)
@@ -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
index 5fbe6d1..ba8057b 100644 (file)
@@ -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
index fa06918..ca910bb 100644 (file)
@@ -27,6 +27,7 @@
 
 #include "i18n.h"
 
+/** @param timeout Timeout in seconds */
 Socket::Socket (int timeout)
        : _deadline (_io_service)
        , _socket (_io_service)
index cc31755..8b2bcce 100644 (file)
@@ -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)
 {
index a9e119d..e43325f 100644 (file)
@@ -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)
index 27ae64a..fe18f8b 100644 (file)
@@ -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 ();
index 99a8c0d..c2f82e1 100644 (file)
@@ -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)
        {}
index 62accfa..3935e23 100644 (file)
@@ -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)
index 704ac7b..8b0274a 100644 (file)
@@ -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;
 
index 56dce56..82a40d5 100644 (file)
@@ -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
 {
index e8fcb5a..9f473d7 100644 (file)
@@ -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 ();
index 36e4dfa..455b271 100644 (file)
@@ -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:
 
index 7a29738..2fb1ad1 100644 (file)
@@ -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)
index 13ef0db..8718223 100644 (file)
@@ -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)
index c5fc3dd..84871aa 100644 (file)
@@ -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 ();
index dacc8bf..31f336b 100644 (file)
@@ -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)
index 311f9cc..185273e 100644 (file)
@@ -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 */
index b7fb52e..2e53a6a 100644 (file)
@@ -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
index 6abbbca..aa365ea 100644 (file)
@@ -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)
 {
index 335e260..0b19a6e 100644 (file)
@@ -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>);
index 3503808..5c885e4 100644 (file)
@@ -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)
index 6429394..8901157 100644 (file)
@@ -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,
index c8b577c..aac2b6e 100644 (file)
@@ -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,
index ff78785..c4371a5 100644 (file)
@@ -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
                );
index 2b38153..6d04796 100644 (file)
@@ -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 {
index 79b5b17..17108c2 100644 (file)
@@ -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)
 {
index 5419a46..14ad693 100644 (file)
@@ -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;
index de2fb1d..21ef60b 100644 (file)
@@ -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)
index 0095ad9..50cbfdf 100644 (file)
@@ -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 ();
 
index 38770f4..574d1d8 100644 (file)
@@ -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.
  */
index 14b21f3..2a78637 100644 (file)
@@ -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.
  */
 
index ebccd53..8a38c8a 100644 (file)
@@ -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,
index 37d4256..41be90b 100644 (file)
@@ -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);
 
index 744d0a7..e162aca 100644 (file)
@@ -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,
index edf5d3b..7dd7e4e 100644 (file)
@@ -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)
 {
index bef0851..ee7d4ae 100644 (file)
 
 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)
 {
index 7519259..77540fc 100644 (file)
@@ -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)
index fda3761..a13c6a6 100644 (file)
@@ -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;
 };
-
index 35ed082..9cced49 100644 (file)
@@ -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.
  */
 
index 033796a..e6e2cc7 100644 (file)
 
 */
 
+/** @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.
  */
index 1d2d171..db64bc7 100644 (file)
 
 */
 
+/** @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.
  */
index 78f8e68..bb05386 100644 (file)
 
 */
 
+/** @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>
index 82ae9e5..e3917af 100644 (file)
 
 */
 
+/** @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"
index e8c3f35..054eddb 100644 (file)
@@ -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"
index e21f41c..fab9411 100644 (file)
@@ -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
index b1689a6..92a415a 100644 (file)
@@ -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>
index 7489e7a..f49d29a 100644 (file)
 
 */
 
+/** @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>
index 7395fe4..b96cb7a 100644 (file)
 
 */
 
+/** @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"
index a7e2ca0..716cf50 100644 (file)
 
 */
 
+/** @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"
index 1e90485..ec5752b 100644 (file)
@@ -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"
index 748695e..7cdecb2 100644 (file)
@@ -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 ().
  */
index 46d82b0..26fab5f 100644 (file)
@@ -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.
index 2fec7a3..6bda8f2 100644 (file)
@@ -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"
index 4113160..0233db1 100644 (file)
@@ -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>
index f9371f7..85a1e78 100644 (file)
@@ -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>
index d7fe027..e0eeba0 100644 (file)
 
 */
 
+/** @file  test/file_log_test.cc
+ *  @brief Test FileLog.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/file_log.h"
 #include <boost/test/unit_test.hpp>
 #include <iostream>
index f4235de..8951f83 100644 (file)
 
 */
 
+/** @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"
index 4dfd6f2..3fd4ba9 100644 (file)
@@ -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>
index 592b7af..9521e39 100644 (file)
@@ -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>
index 69f8c9f..113c24d 100644 (file)
 
 */
 
+/** @file  test/image_filename_sorter_test.cc
+ *  @brief Test ImageFilenameSorter
+ *  @ingroup selfcontained
+ */
+
 #include "lib/image_filename_sorter.h"
 #include <boost/test/unit_test.hpp>
 
index cd0396d..163a3a4 100644 (file)
 
 */
 
+/** @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"
index 8883c2d..1068ed5 100644 (file)
 
 */
 
+/** @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"
index bb47fa9..cc224aa 100644 (file)
 
 */
 
+/** @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"
index ed8f5d9..a941b4a 100644 (file)
 
 */
 
+/** @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"
index 93288c3..95e45e0 100644 (file)
@@ -20,6 +20,7 @@
 
 /** @file  test/recover_test.cc
  *  @brief Test recovery of a DCP transcode after a crash.
+ *  @ingroup specific
  */
 
 #include "test.h"
index 90d6f09..1e37301 100644 (file)
 
 */
 
+/** @file  test/rect_test.cc
+ *  @brief Test Rect class.
+ *  @ingroup selfcontained
+ */
+
 #include "lib/rect.h"
 #include <boost/test/unit_test.hpp>
 #include <iostream>
index 1951d53..a9ed07e 100644 (file)
 
 */
 
+/** @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"
index 79c0e78..4276a2b 100644 (file)
 
 */
 
+/** @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>
index 7eac4e1..3ca9a73 100644 (file)
@@ -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
  */
index a34604d..bcb53bd 100644 (file)
 
 */
 
+/** @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"
index 5ac5c75..1327697 100644 (file)
@@ -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>
index 1eb5020..6c7d0b5 100644 (file)
@@ -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"
index 535efac..97aadb2 100644 (file)
@@ -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
  */
index ecf2130..9b9e6b5 100644 (file)
@@ -20,6 +20,7 @@
 
 /** @file  test/srt_subtitle_test.cc
  *  @brief Test writing DCPs with subtitles from .srt.
+ *  @ingroup specific
  */
 
 #include "lib/film.h"
index ed8c204..63a90b4 100644 (file)
 
 */
 
+/** @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"
index 4ffbdf0..30de1f1 100644 (file)
@@ -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>
index 391d30d..4524242 100644 (file)
 
 */
 
+/** @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"
index b941a5a..958e716 100644 (file)
@@ -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"
index 621b057..7726657 100644 (file)
 
 */
 
+/** @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"
 
index 99c8972..2dcceda 100644 (file)
 
 */
 
+/** @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"
index c7b0669..981ed43 100644 (file)
 
 */
 
+/** @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"
index 80d167e..ac8256b 100644 (file)
 
 */
 
+/** @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"
index e7fddd7..202243d 100644 (file)
 
 */
 
+/** @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"
index bdd3571..9104702 100644 (file)
 
 */
 
+/** @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"