Add additional API documentation

src/AppInfo.h

@@ -2,6 +2,10 @@
 
 #include <string>
 
+/** This class provides project-specific updater properties,
+  * such as the name of the application being updated and
+  * the path to log details of the update install to.
+  */
 class AppInfo
 {
 	public:

src/DirIterator.h

@@ -8,6 +8,9 @@
 #include <dirent.h>
 #endif
 
+/** Simple class for iterating over the files in a directory
+  * and reporting their names and types.
+  */
 class DirIterator
 {
 	public:

src/FileOps.h

@@ -5,9 +5,15 @@
 
 #include "StringUtils.h"
 
+/** A set of functions for performing common operations
+  * on files, throwing exceptions if an operation fails.
+  */
 class FileOps
 {
 	public:
+		/** Base class for exceptions reported by
+		  * FileOps methods if an operation fails.
+		  */
 		class IOException : public std::exception
 		{
 			public:
@@ -25,6 +31,7 @@ class FileOps
 				int m_errno;
 		};
 
+		/** Reproduction of Qt's QFile::Permission enum. */
 		enum QtFilePermission
 		{
 			ReadOwner  = 0x4000,
@@ -52,20 +59,39 @@ class FileOps
 		 */
 		static void removeFile(const char* src) throw (IOException);
 
+		/** Set the permissions of a file using a combination of flags
+		  * from the QtFilePermission enum.
+		  */
 		static void setQtPermissions(const char* path, int permissions) throw (IOException);
 		static bool fileExists(const char* path) throw (IOException);
 		static void moveFile(const char* src, const char* dest) throw (IOException);
-		static void extractFromZip(const char* zipFile, const char* src, const char* dest) throw (IOException);
 		static void mkdir(const char* dir) throw (IOException);
 		static void rmdir(const char* dir) throw (IOException);
 		static void createSymLink(const char* link, const char* target) throw (IOException);
 		static void touch(const char* path) throw (IOException);
+
+		/** Returns the file name part of a file path, including the extension. */
 		static std::string fileName(const char* path);
+
+		/** Returns the directory part of a file path. */
 		static std::string dirname(const char* path);
+
+		/** Remove a directory and all of its contents. */
 		static void rmdirRecursive(const char* dir) throw (IOException);
+
+		/** Return the full, absolute path to a file, resolving any
+		  * symlinks and removing redundant sections.
+		  */
 		static std::string canonicalPath(const char* path);
+
+		/** Returns the path to a directory for storing temporary files. */
 		static std::string tempPath();
 
+		/** Extract the file @p src from the zip archive @p zipFile and
+		  * write it to @p dest.
+		  */
+		static void extractFromZip(const char* zipFile, const char* src, const char* dest) throw (IOException);
+
 	private:
 		static int toUnixPermissions(int qtPermissions);
 

src/ProcessUtils.h

@@ -5,6 +5,9 @@
 #include <list>
 #include <string>
 
+/** A set of functions to get information about the current
+  * process and launch new processes.
+  */
 class ProcessUtils
 {
 	public:
@@ -18,11 +21,22 @@ class ProcessUtils
 
 		static PLATFORM_PID currentProcessId();
 
+		/** Returns the absolute path to the main binary for
+		  * the current process.
+		  */
 		static std::string currentProcessPath();
 
+		/** Start a process and wait for it to finish before
+		  * returning its exit code.
+		  *
+		  * Returns -1 if the process cannot be started.
+		  */
 		static int runSync(const std::string& executable,
 		                    const std::list<std::string>& args);
 
+		/** Start a process and return without waiting for
+		  * it to finish.
+		  */
 		static void runAsync(const std::string& executable,
 		                     const std::list<std::string>& args);
 
@@ -35,6 +49,10 @@ class ProcessUtils
 		static int runElevated(const std::string& executable,
 		                        const std::list<std::string>& args);
 
+		/** Wait for a process to exit.
+		  * Returns true if the process was found and has exited or false
+		  * otherwise.
+		  */
 		static bool waitForProcess(PLATFORM_PID pid);
 
 #ifdef PLATFORM_WINDOWS

src/UpdateInstaller.h

@@ -9,6 +9,11 @@
 
 class UpdateObserver;
 
+/** Central class responsible for installing updates,
+  * launching an elevated copy of the updater if required
+  * and restarting the main application once the update
+  * is installed.
+  */
 class UpdateInstaller
 {
 	public:

src/UpdateMessage.h

@@ -2,6 +2,10 @@
 
 #include <string>
 
+/** UpdateMessage stores information for a message
+  * about the status of update installation sent
+  * between threads.
+  */
 class UpdateMessage
 {
 	public:

src/UpdateObserver.h

@@ -2,6 +2,9 @@
 
 #include <string>
 
+/** Base class for observers of update installation status.
+  * See UpdateInstaller::setObserver()
+  */
 class UpdateObserver
 {
 	public:

src/UpdateScript.h

@@ -5,6 +5,9 @@
 
 class TiXmlElement;
 
+/** Represents a package containing one or more
+  * files for an update.
+  */
 class UpdateScriptPackage
 {
 	public:
@@ -26,6 +29,7 @@ class UpdateScriptPackage
 		}
 };
 
+/** Represents a file to be installed as part of an update. */
 class UpdateScriptFile
 {
 	public:
@@ -50,11 +54,17 @@ class UpdateScriptFile
 		}
 };
 
+/** Stores information about the packages and files included
+  * in an update, parsed from an XML file.
+  */
 class UpdateScript
 {
 	public:
 		UpdateScript();
 
+		/** Initialize this UpdateScript with the script stored
+		  * in the XML file at @p path.
+		  */
 		void parse(const std::string& path);
 
 		bool isValid() const;

src/UpdaterOptions.h

@@ -2,6 +2,7 @@
 
 #include "UpdateInstaller.h"
 
+/** Parses the command-line options to the updater binary. */
 class UpdaterOptions
 {
 	public: