Document ffmpegsource_common.cpp/h.

Originally committed to SVN as r3363.

aegisub/src/ffmpegsource_common.cpp

@@ -51,17 +51,14 @@
 #include <map>
 
 
-
-/// DOCME
 wxMutex FFmpegSourceProvider::CleaningInProgress;
 
 
-
+/// @brief Callback function that updates the indexing progress dialog
-/// @brief Update indexing progress 
+/// @param Current	The current file positition in bytes
-/// @param Current 
+/// @param Total	The total file size in bytes
-/// @param Total   
+/// @param Private	A pointer to the progress dialog box to update 
-/// @param Private 
+/// @return			Returns non-0 if indexing is cancelled, 0 otherwise.
-/// @return 
 ///
 int FFMS_CC FFmpegSourceProvider::UpdateIndexingProgress(int64_t Current, int64_t Total, void *Private) {
 	IndexingProgressDialog *Progress = (IndexingProgressDialog *)Private;
@@ -77,12 +74,12 @@ int FFMS_CC FFmpegSourceProvider::UpdateIndexingProgress(int64_t Current, int64_
 
 
 
-/// @brief Do indexing 
+/// @brief Does indexing of a source file
-/// @param Indexer            
+/// @param Indexer		A pointer to the indexer object representing the file to be indexed
-/// @param CacheName          
+/// @param CacheName    The filename of the output index file
-/// @param Trackmask          
+/// @param Trackmask    A binary mask of the track numbers to index
-/// @param IgnoreDecodeErrors 
+/// @param IgnoreDecodeErrors	True if audio decoding errors will be tolerated, false otherwise
-/// @return 
+/// @return				Returns the index object on success, NULL otherwise
 ///
 FFIndex *FFmpegSourceProvider::DoIndexing(FFIndexer *Indexer, const wxString &CacheName, int Trackmask, bool IgnoreDecodeErrors) {
 	char FFMSErrMsg[1024];
@@ -121,11 +118,10 @@ FFIndex *FFmpegSourceProvider::DoIndexing(FFIndexer *Indexer, const wxString &Ca
 
 
 
-/// @brief Find all tracks of the given typo and return their track numbers and respective codec names 
+/// @brief Finds all tracks of the given type and return their track numbers and respective codec names 
-/// @param Indexer 
+/// @param Indexer	The indexer object representing the source file
-/// @param Type    
+/// @param Type		The track type to look for
-/// @return 
+/// @return			Returns a std::map with the track numbers as keys and the codec names as values.
-///
 std::map<int,wxString> FFmpegSourceProvider::GetTracksOfType(FFIndexer *Indexer, FFMS_TrackType Type) {
 	std::map<int,wxString> TrackList;
 	int NumTracks = FFMS_GetNumTracksI(Indexer);
@@ -143,10 +139,9 @@ std::map<int,wxString> FFmpegSourceProvider::GetTracksOfType(FFIndexer *Indexer,
 
 
 /// @brief Ask user for which track he wants to load 
-/// @param TrackList 
+/// @param TrackList	A std::map with the track numbers as keys and codec names as values
-/// @param Type      
+/// @param Type			The track type to ask about
-/// @return 
+/// @return				Returns the track number chosen (an integer >= 0) on success, or a negative integer if the user cancelled.
-///
 int FFmpegSourceProvider::AskForTrackSelection(const std::map<int,wxString> &TrackList, FFMS_TrackType Type) {
 	std::vector<int> TrackNumbers;
 	wxArrayString Choices;
@@ -173,7 +168,6 @@ int FFmpegSourceProvider::AskForTrackSelection(const std::map<int,wxString> &Tra
 
 
 /// @brief Set ffms2 log level according to setting in config.dat 
-///
 void FFmpegSourceProvider::SetLogLevel() {
 	wxString LogLevel = Options.AsText(_T("FFmpegSource log level"));
 
@@ -197,10 +191,9 @@ void FFmpegSourceProvider::SetLogLevel() {
 
 
 
-/// @brief method by amz Creates a name for the ffmpegsource2 index and prepares the folder if it doesn't exist 
+/// @brief	Generates an unique name for the ffms2 index file and prepares the cache folder if it doesn't exist 
-/// @param filename 
+/// @param filename	The name of the source file
-/// @return 
+/// @return			Returns the generated filename.
-///
 wxString FFmpegSourceProvider::GetCacheFilename(const wxString& filename)
 {
 	// Get the size of the file to be hashed
@@ -238,9 +231,8 @@ wxString FFmpegSourceProvider::GetCacheFilename(const wxString& filename)
 }
 
 
-/// @brief fire and forget cleaning thread (well, almost) 
+/// @brief		Starts the cache cleaner thread
-/// @return 
+/// @return		True on success, false if the thread could not be started.
-///
 bool FFmpegSourceProvider::CleanCache() {
 	wxLogDebug(_T("FFmpegSourceCacheCleaner: attempting to start thread"));
 
@@ -266,15 +258,14 @@ bool FFmpegSourceProvider::CleanCache() {
 
 
 /// @brief constructor 
-/// @param par 
+/// @param par	the parent provider
-///
 FFmpegSourceCacheCleaner::FFmpegSourceCacheCleaner(FFmpegSourceProvider *par) : wxThread(wxTHREAD_DETACHED) {
 	parent = par;
 }
 
 
-/// @brief all actual work happens here because I was too lazy to write more functions 
+/// @brief	Cleans the ffms2 index cache folder
-///
+/// @return	Returns non-0 on error, 0 otherwise.
 wxThread::ExitCode FFmpegSourceCacheCleaner::Entry() {
 	wxMutexLocker lock(FFmpegSourceProvider::CleaningInProgress);
 	if (!lock.IsOk()) {

aegisub/src/ffmpegsource_common.h

@@ -42,72 +42,41 @@
 #include <wx/wxprec.h>
 #include <wx/thread.h>
 #include "include/aegisub/aegisub.h"
-
-/// DOCME
-#define FFMS_BETA_10_COMPAT
 #include <ffms.h>
 #include "dialog_progress.h"
 
 
-
+/// Index all tracks
-/// DOCME
 #define FFMS_TRACKMASK_ALL		-1
-
+/// Index no tracks
-/// DOCME
 #define FFMS_TRACKMASK_NONE		0
 
 
-
-/// DOCME
 /// @class FFmpegSourceProvider
-/// @brief DOCME
+/// @brief Base class for FFMS2 source providers; contains common functions etc
-///
-/// DOCME
 class FFmpegSourceProvider {
 	friend class FFmpegSourceCacheCleaner;
 public:
-
+	/// Logging level constants from avutil/log.h
-	/// DOCME
 	enum FFMS_LogLevel {
-
+		/// nothing printed
-		/// DOCME
 		FFMS_LOG_QUIET		= -8,
-
-		/// DOCME
 		FFMS_LOG_PANIC		= 0,
-
-		/// DOCME
 		FFMS_LOG_FATAL		= 8,
-
-		/// DOCME
 		FFMS_LOG_ERROR		= 16,
-
-		/// DOCME
 		FFMS_LOG_WARNING	= 24,
-
-		/// DOCME
 		FFMS_LOG_INFO		= 32,
-
-		/// DOCME
 		FFMS_LOG_VERBOSE	= 40,
-
-		/// DOCME
 		FFMS_LOG_DEBUG		= 48,
 	};
 
-
+	/// Indexing progress report dialog
-	/// DOCME
 	struct IndexingProgressDialog {
-
-		/// DOCME
 		volatile bool IndexingCanceled;
-
-		/// DOCME
 		DialogProgress *ProgressDialog;
 	};
 
-
+	/// Mutex preventing two cache cleaner threads from running at the same time
-	/// DOCME
 	static wxMutex CleaningInProgress;
 	bool CleanCache();
 
@@ -119,30 +88,20 @@ public:
 	wxString GetCacheFilename(const wxString& filename);
 	void SetLogLevel();
 
-
-	/// @brief DOCME
-	///
 	virtual ~FFmpegSourceProvider() {}
 };
 
 
 
-/// DOCME
 /// @class FFmpegSourceCacheCleaner
-/// @brief DOCME
+/// @brief Implements index cache cleaning functionality for the FFMS2 providers 
-///
-/// DOCME
 class FFmpegSourceCacheCleaner : public wxThread {
 private:
-
-	/// DOCME
 	FFmpegSourceProvider *parent;
 
 public:
 	FFmpegSourceCacheCleaner(FFmpegSourceProvider *par);
 
-	/// @brief DOCME
-	///
 	~FFmpegSourceCacheCleaner() {};
 	wxThread::ExitCode Entry();
 };