From: Carl Hetherington <cth@carlh.net>
Date: Mon, 24 Sep 2012 00:58:56 +0000 (+0100)
Subject: Some doxygen documentation improvements.
X-Git-Tag: v2.0.48~1720^2~20
X-Git-Url: https://git.carlh.net/gitweb/?p=dcpomatic.git;a=commitdiff_plain;h=3fc9a435a720d8b2abd78c1bdc7b34bc635ad797

Some doxygen documentation improvements.
---

diff --git a/Doxyfile b/Doxyfile
index 80a4b9c25..56f7e1d3c 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -661,7 +661,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = src \
+INPUT                  = src/lib src/wx src/tools \
                          doc/mainpage.txt
 
 # This tag can be used to specify the character encoding of the source files
diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index 81c3b4558..e89ca8d26 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -23,7 +23,7 @@
  *  and libsndfile (http://www.mega-nerd.com/libsndfile/) for WAV file manipulation.  It
  *  also makes heavy use of the boost libraries (http://www.boost.org/).  libtiff
  *  (http://www.libtiff.org/) is used for TIFF encoding and decoding, and the GUI is
- *  built using GTK (http://www.gtk.org/) and GTKMM (http://www.gtkmm.org).  It also uses libmhash (http://mhash.sourceforge.net/)
+ *  built using wxWidgets (http://wxwidgets.org/).  It also uses libmhash (http://mhash.sourceforge.net/)
  *  for debugging purposes.
  *
  *  Thanks are due to the authors and communities of all DVD-o-matic's dependencies.
diff --git a/src/lib/config.h b/src/lib/config.h
index b002da7df..840dcdaef 100644
--- a/src/lib/config.h
+++ b/src/lib/config.h
@@ -81,18 +81,22 @@ public:
 		return _reference_filters;
 	}
 
+	/** @return The IP address of a TMS that we can copy DCPs to */
 	std::string tms_ip () const {
 		return _tms_ip;
 	}
 
+	/** @return The path on a TMS that we should write DCPs to */
 	std::string tms_path () const {
 		return _tms_path;
 	}
 
+	/** @return User name to log into the TMS with */
 	std::string tms_user () const {
 		return _tms_user;
 	}
 
+	/** @return Password to log into the TMS with */
 	std::string tms_password () const {
 		return _tms_password;
 	}
@@ -146,21 +150,25 @@ public:
 		Changed ();
 	}
 
+	/** @param i IP address of a TMS that we can copy DCPs to */
 	void set_tms_ip (std::string i) {
 		_tms_ip = i;
 		Changed ();
 	}
 
+	/** @param p Path on a TMS that we should write DCPs to */
 	void set_tms_path (std::string p) {
 		_tms_path = p;
 		Changed ();
 	}
 
+	/** @param u User name to log into the TMS with */
 	void set_tms_user (std::string u) {
 		_tms_user = u;
 		Changed ();
 	}
 
+	/** @param p Password to log into the TMS with */
 	void set_tms_password (std::string p) {
 		_tms_password = p;
 		Changed ();
@@ -189,21 +197,21 @@ private:
 
 	/** J2K encoding servers to use */
 	std::vector<ServerDescription *> _servers;
-
 	/** Screen definitions */
 	std::vector<boost::shared_ptr<Screen> > _screens;
-
 	/** Scaler to use for the "A" part of A/B comparisons */
 	Scaler const * _reference_scaler;
-
 	/** Filters to use for the "A" part of A/B comparisons */
 	std::vector<Filter const *> _reference_filters;
-
+	/** The IP address of a TMS that we can copy DCPs to */
 	std::string _tms_ip;
+	/** The path on a TMS that we should write DCPs to */
 	std::string _tms_path;
+	/** User name to log into the TMS with */
 	std::string _tms_user;
+	/** Password to log into the TMS with */
 	std::string _tms_password;
-
+	/** Our sound processor */
 	SoundProcessor const * _sound_processor;
 
 	/** Singleton instance, or 0 */
diff --git a/src/lib/decoder.cc b/src/lib/decoder.cc
index fc808d819..9332511bc 100644
--- a/src/lib/decoder.cc
+++ b/src/lib/decoder.cc
@@ -87,6 +87,7 @@ Decoder::~Decoder ()
 	delete _delay_line;
 }
 
+/** Start off a decode processing run */
 void
 Decoder::process_begin ()
 {
@@ -120,6 +121,7 @@ Decoder::process_begin ()
 	_audio_frames_processed = 0;
 }
 
+/** Finish off a decode processing run */
 void
 Decoder::process_end ()
 {
diff --git a/src/lib/encoder.cc b/src/lib/encoder.cc
index 18ccd3f57..62ba922da 100644
--- a/src/lib/encoder.cc
+++ b/src/lib/encoder.cc
@@ -60,6 +60,7 @@ Encoder::current_frames_per_second () const
 	return _history_size / (seconds (now) - seconds (_time_history.back ()));
 }
 
+/** @return true if the last frame to be processed was skipped as it already existed */
 bool
 Encoder::skipping () const
 {
@@ -67,6 +68,7 @@ Encoder::skipping () const
 	return _just_skipped;
 }
 
+/** @return Index of last frame to be successfully encoded */
 int
 Encoder::last_frame () const
 {
@@ -74,6 +76,9 @@ Encoder::last_frame () const
 	return _last_frame;
 }
 
+/** Should be called when a frame has been encoded successfully.
+ *  @param n Frame index.
+ */
 void
 Encoder::frame_done (int n)
 {
diff --git a/src/lib/encoder.h b/src/lib/encoder.h
index 5c0c4c03f..539b2912c 100644
--- a/src/lib/encoder.h
+++ b/src/lib/encoder.h
@@ -84,10 +84,15 @@ protected:
 
 	/** Mutex for _time_history, _just_skipped and _last_frame */
 	mutable boost::mutex _history_mutex;
+	/** List of the times of completion of the last _history_size frames;
+	    first is the most recently completed.
+	*/
 	std::list<struct timeval> _time_history;
+	/** Number of frames that we should keep history for */
 	static int const _history_size;
 	/** true if the last frame we processed was skipped (because it was already done) */
 	bool _just_skipped;
+	/** Index of the last frame to be processed */
 	int _last_frame;
 };
 
diff --git a/src/lib/exceptions.h b/src/lib/exceptions.h
index 6b567805b..8ef09875b 100644
--- a/src/lib/exceptions.h
+++ b/src/lib/exceptions.h
@@ -77,6 +77,9 @@ public:
 class FileError : public StringError
 {
 public:
+	/** @param m Error message.
+	 *  @param f Name of the file that this exception concerns.
+	 */
 	FileError (std::string m, std::string f)
 		: StringError (m)
 		, _file (f)
@@ -84,11 +87,13 @@ public:
 
 	virtual ~FileError () throw () {}
 
+	/** @return name of the file that this exception concerns */
 	std::string file () const {
 		return _file;
 	}
 
 private:
+	/** name of the file that this exception concerns */
 	std::string _file;
 };
 	
diff --git a/src/lib/job.cc b/src/lib/job.cc
index d446b3913..22754eb90 100644
--- a/src/lib/job.cc
+++ b/src/lib/job.cc
@@ -223,7 +223,7 @@ Job::set_error (string e)
 	_error = e;
 }
 
-/** Set that this job's progress will always be unknown */
+/** Say that this job's progress will always be unknown */
 void
 Job::set_progress_unknown ()
 {
@@ -231,6 +231,7 @@ Job::set_progress_unknown ()
 	_progress_unknown = true;
 }
 
+/** @return Human-readable status of this job */
 string
 Job::status () const
 {
@@ -252,6 +253,7 @@ Job::status () const
 	return s.str ();
 }
 
+/** @return An estimate of the remaining time for this job, in seconds */
 int
 Job::remaining_time () const
 {
diff --git a/src/lib/job.h b/src/lib/job.h
index 95599bdbb..fee887b42 100644
--- a/src/lib/job.h
+++ b/src/lib/job.h
@@ -72,6 +72,7 @@ protected:
 
 	virtual int remaining_time () const;
 
+	/** Description of a job's state */
 	enum State {
 		NEW,           ///< the job hasn't been started yet
 		RUNNING,       ///< the job is running
@@ -82,10 +83,11 @@ protected:
 	void set_state (State);
 	void set_error (std::string e);
 
+	/** FilmState for this job */
 	boost::shared_ptr<const FilmState> _fs;
+	/** options in use for this job */
 	boost::shared_ptr<const Options> _opt;
-
-	/** A log that this job can write to */
+	/** a log that this job can write to */
 	Log* _log;
 
 private:
@@ -94,11 +96,15 @@ private:
 
 	/** mutex for _state and _error */
 	mutable boost::mutex _state_mutex;
+	/** current state of the job */
 	State _state;
+	/** message for an error that has occurred (when state == FINISHED_ERROR) */
 	std::string _error;
 
+	/** time that this job was started */
 	time_t _start_time;
-	
+
+	/** mutex for _stack and _progress_unknown */
 	mutable boost::mutex _progress_mutex;
 
 	struct Level {
diff --git a/src/lib/util.cc b/src/lib/util.cc
index d12bd3e77..73222083a 100644
--- a/src/lib/util.cc
+++ b/src/lib/util.cc
@@ -369,6 +369,9 @@ md5_data (string title, void const * data, int size)
 }
 #endif
 
+/** @param file File name.
+ *  @return MD5 digest of file's contents.
+ */
 string
 md5_digest (string file)
 {
@@ -404,6 +407,9 @@ md5_digest (string file)
 	return s.str ();
 }
 
+/** @param An arbitrary sampling rate.
+ *  @return The appropriate DCP-approved sampling rate (48kHz or 96kHz).
+ */
 int
 dcp_audio_sample_rate (int fs)
 {
@@ -424,6 +430,9 @@ bool operator!= (Crop const & a, Crop const & b)
 	return !(a == b);
 }
 
+/** @param index Colour LUT index.
+ *  @return Human-readable name.
+ */
 string
 colour_lut_index_to_name (int index)
 {
@@ -458,6 +467,10 @@ Socket::check ()
 	_deadline.async_wait (boost::bind (&Socket::check, this));
 }
 
+/** Blocking connect with timeout.
+ *  @param endpoint End-point to connect to.
+ *  @param timeout Time-out in seconds.
+ */
 void
 Socket::connect (asio::ip::basic_resolver_entry<asio::ip::tcp> const & endpoint, int timeout)
 {
@@ -472,6 +485,11 @@ Socket::connect (asio::ip::basic_resolver_entry<asio::ip::tcp> const & endpoint,
 	}
 }
 
+/** Blocking write with timeout.
+ *  @param data Buffer to write.
+ *  @param size Number of bytes to write.
+ *  @param timeout Time-out, in seconds.
+ */
 void
 Socket::write (uint8_t const * data, int size, int timeout)
 {
@@ -488,6 +506,11 @@ Socket::write (uint8_t const * data, int size, int timeout)
 	}
 }
 
+/** Blocking read with timeout.
+ *  @param data Buffer to read to.
+ *  @param size Number of bytes to read.
+ *  @param timeout Time-out, in seconds.
+ */
 int
 Socket::read (uint8_t* data, int size, int timeout)
 {
diff --git a/src/lib/util.h b/src/lib/util.h
index d7f233003..63d492e60 100644
--- a/src/lib/util.h
+++ b/src/lib/util.h
@@ -80,19 +80,25 @@ struct Size
 	int height;
 };
 
+/** A description of the crop of an image or video. */
 struct Crop
 {
 	Crop () : left (0), right (0), top (0), bottom (0) {}
-	
+
+	/** Number of pixels to remove from the left-hand side */
 	int left;
+	/** Number of pixels to remove from the right-hand side */
 	int right;
+	/** Number of pixels to remove from the top */
 	int top;
+	/** Number of pixels to remove from the bottom */
 	int bottom;
 };
 
 extern bool operator== (Crop const & a, Crop const & b);
 extern bool operator!= (Crop const & a, Crop const & b);
 
+/** A position */
 struct Position
 {
 	Position ()
@@ -105,7 +111,9 @@ struct Position
 		, y (y_)
 	{}
 
+	/** x coordinate */
 	int x;
+	/** y coordinate */
 	int y;
 };
 
@@ -113,11 +121,20 @@ extern std::string crop_string (Position, Size);
 extern int dcp_audio_sample_rate (int);
 extern std::string colour_lut_index_to_name (int index);
 
+/** @class Socket
+ *  @brief A class to wrap a boost::asio::ip::tcp::socket with some things
+ *  that are useful for DVD-o-matic.
+ *
+ *  This class wraps some things that I could not work out how to do with boost;
+ *  most notably, sync read/write calls with timeouts, and the ability to peak into
+ *  data being read.
+ */
 class Socket
 {
 public:
 	Socket ();
 
+	/** @return Our underlying socket */
 	boost::asio::ip::tcp::socket& socket () {
 		return _socket;
 	}
diff --git a/src/wx/film_viewer.cc b/src/wx/film_viewer.cc
index 56f20449b..0d17baf83 100644
--- a/src/wx/film_viewer.cc
+++ b/src/wx/film_viewer.cc
@@ -47,6 +47,7 @@ public:
 	{
 	}
 
+	/** Handle a paint event */
 	void paint_event (wxPaintEvent& ev)
 	{
 		if (_current_image != _pending_image) {
@@ -67,6 +68,7 @@ public:
 		}
 	}
 
+	/** Handle a size event */
 	void size_event (wxSizeEvent &)
 	{
 		if (!_image) {
@@ -101,6 +103,7 @@ public:
 		}
 	}
 
+	/** Clear our thumbnail image */
 	void clear ()
 	{
 		delete _bitmap;
diff --git a/src/wx/wx_util.cc b/src/wx/wx_util.cc
index 44d9462e5..4277ed12d 100644
--- a/src/wx/wx_util.cc
+++ b/src/wx/wx_util.cc
@@ -27,6 +27,12 @@
 using namespace std;
 using namespace boost;
 
+/** Add a wxStaticText to a wxSizer, aligning it at vertical centre.
+ *  @param s Sizer to add to.
+ *  @param p Parent window for the wxStaticText.
+ *  @param t Text for the wxStaticText.
+ *  @param prop Properties to pass when calling Add() on the wxSizer.
+ */
 wxStaticText *
 add_label_to_sizer (wxSizer* s, wxWindow* p, string t, int prop)
 {
@@ -35,6 +41,10 @@ add_label_to_sizer (wxSizer* s, wxWindow* p, string t, int prop)
 	return m;
 }
 
+/** Pop up an error dialogue box.
+ *  @param parent Parent.
+ *  @param m Message.
+ */
 void
 error_dialog (wxWindow* parent, string m)
 {
@@ -43,12 +53,18 @@ error_dialog (wxWindow* parent, string m)
 	d->Destroy ();
 }
 
+/** @param s wxWidgets string.
+ *  @return Corresponding STL string.
+ */
 string
 wx_to_std (wxString s)
 {
 	return string (s.mb_str ());
 }
 
+/** @param s STL string.
+ *  @return Corresponding wxWidgets string.
+ */
 wxString
 std_to_wx (string s)
 {
@@ -75,15 +91,16 @@ ThreadedStaticText::~ThreadedStaticText ()
 	delete _thread;
 }
 
+/** Run our thread and post the result to the GUI thread via AddPendingEvent */
 void
 ThreadedStaticText::run (function<string ()> fn)
 {
-	/* Run the thread and post the result to the GUI thread via AddPendingEvent */
 	wxCommandEvent ev (wxEVT_COMMAND_TEXT_UPDATED, _update_event_id);
 	ev.SetString (std_to_wx (fn ()));
 	GetEventHandler()->AddPendingEvent (ev);
 }
 
+/** Called in the GUI thread when our worker thread has finished */
 void
 ThreadedStaticText::thread_finished (wxCommandEvent& ev)
 {
diff --git a/src/wx/wx_util.h b/src/wx/wx_util.h
index 3a454c7c4..12a6e8837 100644
--- a/src/wx/wx_util.h
+++ b/src/wx/wx_util.h
@@ -30,7 +30,9 @@ extern wxStaticText* add_label_to_sizer (wxSizer *, wxWindow *, std::string, int
 extern std::string wx_to_std (wxString);
 extern wxString std_to_wx (std::string);
 
-/** A wxStaticText whose content is computed in a separate thread, to avoid holding
+/** @class ThreadedStaticText
+ *
+ *  @brief A wxStaticText whose content is computed in a separate thread, to avoid holding
  *  up the GUI while work is done.
  */
 class ThreadedStaticText : public wxStaticText
@@ -43,6 +45,7 @@ private:
 	void run (boost::function<std::string ()> fn);
 	void thread_finished (wxCommandEvent& ev);
 
+	/** Thread to do our work in */
 	boost::thread* _thread;
 	
 	static const int _update_event_id;