DOXYGEN: Doxygen improvements part 3

Editing doxygen comments in files:

- debug.h
- dialogs.h
- encoding.h
- endian.h
- error.h
- events.h
- fft.h
- file.h
- frac.h
- fs.h
- gui_options.h
- hash-ptr.h
- hashmap.h
- huffman.h
- ini-file.h

Plus some small changes in the config file.

common/debug.h

@@ -80,8 +80,11 @@ void debugN(int level, const char *s, ...) GCC_PRINTF(2, 3);
  * if the specified special debug level is active.
  * As a rule of thumb, the more important the message, the lower the level.
  * Automatically appends a newline.
- *
  * @see enableDebugChannel
+ *
+ * @param level         Debug level that must be active for the message to be printed.
+ * @param debugChannels Bitfield of channels to check against.
+ * @param s             Message to print.
  */
 void debugC(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4);
 
@@ -91,8 +94,12 @@ void debugC(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4
  * if the specified special debug level is active.
  * As a rule of thumb, the more important the message, the lower the level.
  * Does not append a newline automatically.
- *
  * @see enableDebugChannel
+ *
+ * @param level         Debug level that must be active for the message to be printed.
+ * @param debugChannels Bitfield of channels to check against.
+ * @param s             Message to print.
+ * 
  */
 void debugCN(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4);
 
@@ -100,8 +107,10 @@ void debugCN(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3,
  * Print a debug message to the text console (stdout), but only if
  * the specified special debug level is active.
  * Automatically appends a newline.
- *
  * @see enableDebugChannel
+ *
+ * @param debugChannels Bitfield of channels to check against.
+ * @param s             Message to print.
  */
 void debugC(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
 
@@ -109,8 +118,10 @@ void debugC(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
  * Print a debug message to the text console (stdout), but only if
  * the specified special debug level is active.
  * Does not append a newline automatically.
- *
  * @see enableDebugChannel
+ *
+ * @param debugChannels Bitfield of channels to check against.
+ * @param s             Message to print.
  */
 void debugCN(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
 
@@ -125,7 +136,7 @@ bool debugLevelSet(int level);
  * Check whether the debug level and channel are active.
  *
  * @param level         Debug level to check against. If set to -1, only channel check is active.
- * @param debugChannels Debug channel to check against.
+ * @param debugChannels Bitfield of channels to check against.
  * @see enableDebugChannel
  */
 bool debugChannelSet(int level, uint32 debugChannels);

common/dialogs.h

@@ -48,24 +48,24 @@ namespace Common {
 class DialogManager {
 public:
 	/**
-	 * Values representing the user response to a dialog
+	 * Values representing the user response to a dialog.
 	 */
 	enum DialogResult {
-		kDialogError = -1,	///< Dialog couldn't be displayed
+		kDialogError = -1,	///< Dialog could not be displayed.
-		kDialogCancel = 0,	///< User cancelled the dialog (Cancel/No/Close buttons)
+		kDialogCancel = 0,	///< User cancelled the dialog (Cancel/No/Close buttons).
-		kDialogOk = 1		///< User confirmed the dialog (OK/Yes buttons)
+		kDialogOk = 1		///< User confirmed the dialog (OK/Yes buttons).
 	};
 
 	DialogManager() : _wasFullscreen(false) {}
 	virtual ~DialogManager() {}
 
 	/**
-	 * Displays a dialog for selecting a file or folder in the filesystem.
+	 * Display a dialog for selecting a file or folder in the file system.
 	 *
-	 * @param title The dialog title
+	 * @param title        Dialog title.
-	 * @param choice The path selected by the user
+	 * @param choice       Path selected by the user.
-	 * @param isDirBrowser Restrict selection to directories
+	 * @param isDirBrowser Restrict selection to directories.
-	 * @return The dialog result
+	 * @return The dialog result.
 	 */
 	virtual DialogResult showFileBrowser(const Common::U32String &title, FSNode &choice, bool isDirBrowser = false) { return kDialogError; }
 

common/encoding.h

@@ -40,47 +40,48 @@ namespace Common {
  */
 
 /**
- * A class, that allows conversion between different text encoding,
+ * A class that allows conversion between different text encoding.
- * the encodings available depend on the current backend and if the
+ * The encodings available depend on the current backend and whether
  * ScummVM is compiled with or without iconv.
  */
 class Encoding {
 	public:
 		/**
-		 * Constructs everything needed for the conversion between 2 encodings
+		 * Construct everything needed for the conversion between two encodings
 		 * and saves the values for future use.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * @param to   Name of the encoding the strings will be converted to.
-		 * @param from Name of the encoding the strings will be converted from
+		 * @param from Name of the encoding the strings will be converted from.
 		 */
 		Encoding(const String &to, const String &from);
 		~Encoding() {};
 
 		/**
-		 * Converts string between encodings. The resulting string is ended by 
+		 * Convert a string between encodings.
-		 * a character with value 0 (C-like ending for 1 byte per character
-		 * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
 		 *
-		 * The result has to be freed after use.
+		 * The resulting string is ended by a character with value 0 
+		 * (C-like ending for 1 byte per character encodings, 2 zero bytes for UTF-16,
+		 * 4 zero bytes for UTF-32).
+		 * The result must be freed after usage using @c free(), not @c delete[].
 		 *
-		 * @param string String that should be converted.
+		 * @param string String to be converted.
 		 * @param length Length of the string to convert in bytes.
 		 *
-		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 * @return Converted string (must be freed) or nullptr if the conversion failed.
 		 */
 		char *convert(const char *string, size_t length);
 
 		/**
-		 * Static version of the method above.
+		 * Convert a string between encodings.
-		 * Converts string between encodings. The resulting string is ended by 
-		 * a character with value 0 (C-like ending for 1 byte per character
-		 * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
 		 *
-		 * The result has to be freed after use.
+		 * This is a static version of the method above.
+		 * The resulting string is ended by a character with value 0
+		 * (C-like ending for 1 byte per character encodings, 2 zero bytes for UTF-16,
+		 * 4 zero bytes for UTF-32). The result must be freed after usage.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * @param to     Name of the encoding the strings will be converted to.
-		 * @param from Name of the encoding the strings will be converted from
+		 * @param from   Name of the encoding the strings will be converted from.
-		 * @param string String that should be converted.
+		 * @param string String to be converted.
 		 * @param length Length of the string to convert in bytes.
 		 *
 		 * @return Converted string (must be freed) or nullptr if the conversion failed
@@ -96,42 +97,46 @@ class Encoding {
 		}
 
 		/**
-		 * @return The encoding, which is currently being converted from
+		 * @return The encoding that is currently being converted from.
 		 */
 		String getFrom() {return _from;};
 
 		/**
-		 * @param from The encoding, to convert from
+		 * @param from The encoding to convert from.
 		 */
 		void setFrom(const String &from) {_from = from;};
 
 		/**
-		 * @return The encoding, which is currently being converted to
+		 * @return The encoding that is currently being converted to.
 		 */
 		String getTo() {return _to;};
 
 		/**
-		 * @param to The encoding, to convert to
+		 * @param to The encoding to convert to.
 		 */
 		void setTo(const String &to) {_to = to;};
 
 		/**
-		 * Switches the endianity of a string.
+		 * Switch the endianness of a string.
 		 *
-		 * @param string Array containing the characters of a string.
+		 * @param string   Array containing the characters of a string.
-		 * @param length Length of the string in bytes
+		 * @param length   Length of the string in bytes.
 		 * @param bitCount Number of bits used for each character.
 		 *
-		 * @return Array of characters with the opposite endianity
+		 * @return Array of characters with the opposite endianness.
 		 */
 		static char *switchEndian(const char *string, int length, int bitCount);
 
 		/**
-		 * Computes length (in bytes) of a string in a given encoding. 
+		 * Compute the length (in bytes) of a string in a given encoding.
-		 * The string must be zero ended. Similar to strlen
-		 * (could be used instead of strlen).
 		 *
-		 * @param string String, which size should be computed.
+		 * The string must be zero ended. Similar to @c strlen.
+		 *
+		 * @note  This function must be used instead of @c strlen for some encodings
+		 *        (such as UTF-16 and UTF-32) because @c strlen does not support
+		 *        multi-byte encodings, with some exceptions (such as UTF-8).
+		 *
+		 * @param string   The string whose size to compute.
 		 * @param encoding Encoding of the string.
 		 *
 		 * @return Size of the string in bytes.
@@ -139,91 +144,93 @@ class Encoding {
 		static size_t stringLength(const char *string, const String &encoding);
 	
 	private:
-		/** The encoding, which is currently being converted to */
+		/** The encoding that is currently being converted to. */
 		String _to;
 
-		/** The encoding, which is currently being converted from */
+		/** The encoding that is currently being converted from. */
 		String _from;
 
 		/**
-		 * Takes care of transliteration and calls conversion
+		 * Take care of transliteration and call conversion.
 		 *
-		 * The result has to be freed after use.
+		 * The result must be freed after usage.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * @param to     Name of the encoding the strings will be converted to.
-		 * @param from Name of the encoding the strings will be converted from
+		 * @param from   Name of the encoding the strings will be converted from.
-		 * @param string String that should be converted.
+		 * @param string The string to convert.
 		 * @param length Length of the string to convert in bytes.
 		 *
-		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 * @return Converted string (must be freed) or nullptr if the conversion failed.
 		 */
 		static char *convertWithTransliteration(const String &to, const String &from, const char *string, size_t length);
 
 		/**
-		 * Calls as many conversion functions as possible or until the conversion
+		 * Call as many conversion functions as possible, or until the conversion
-		 * succeeds. It first tries to use iconv, then it tries to use platform
+		 * succeeds.
-		 * specific functions and after that it tries to use TransMan mapping.
 		 *
-		 * The result has to be freed after use.
+		 * It first tries to use iconv, then it tries to use platform
+		 * specific functions, and after that, it tries to use TransMan mapping.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * The result must be freed after usage.
-		 * @param from Name of the encoding the strings will be converted from
+		 *
-		 * @param string String that should be converted.
+		 * @param to     Name of the encoding the strings will be converted to.
+		 * @param from   Name of the encoding the strings will be converted from.
+		 * @param string The string to convert.
 		 * @param length Length of the string to convert in bytes.
 		 *
-		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 * @return Converted string (must be freed) or nullptr if the conversion failed.
 		 */
 		static char *conversion(const String &to, const String &from, const char *string, size_t length);
 
 		/**
-		 * Tries to convert the string using iconv.
+		 * Attempt to convert the string using iconv.
 		 *
-		 * The result has to be freed after use.
+		 * The result must be freed after usage.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * @param to     Name of the encoding the strings will be converted to.
-		 * @param from Name of the encoding the strings will be converted from
+		 * @param from   Name of the encoding the strings will be converted from.
-		 * @param string String that should be converted.
+		 * @param string The string to convert.
 		 * @param length Length of the string to convert in bytes.
 		 *
-		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 * @return Converted string (must be freed) or nullptr if the conversion failed.
 		 */
 		static char *convertIconv(const char *to, const char *from, const char *string, size_t length);
 
 		/**
-		 * Uses conversion table to convert the string to unicode and from that
+		 * Use a conversion table to convert the string to unicode, and from that,
-		 * to the final encoding. Important encodings, that aren't supported by
+		 * to the final encoding. Important encodings, that are not supported by
 		 * all backends should go here.
 		 *
-		 * The result has to be freed after use.
+		 * The result must be freed after usage.
 		 *
-		 * @param to Name of the encoding the strings will be converted to
+		 * @param to     Name of the encoding the strings will be converted to.
-		 * @param from Name of the encoding the strings will be converted from
+		 * @param from   Name of the encoding the strings will be converted from.
-		 * @param string String that should be converted.
+		 * @param string The string to be converted.
 		 * @param length Length of the string to convert in bytes.
 		 *
-		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 * @return Converted string (must be freed) or nullptr if the conversion failed.
 		 */
 		static char *convertConversionTable(const char *to, const char *from, const char *string, size_t length);
 
 		/**
-		 * Transliterates cyrillic string in iso-8859-5 encoding and returns
+		 * Transliterate a Cyrillic string in ISO-8859-5 encoding and return
-		 * it's ASCII (latin) form.
+		 * its ASCII (Latin) form.
 		 *
-		 * The result has to be freed after use.
+		 * The result must be freed after usage.
 		 *
-		 * @param string String that should be converted
+		 * @param string The string to convert.
 		 *
 		 * @return Transliterated string in ASCII (must be freed) or nullptr on fail.
 		 */
 		static char *transliterateCyrillic(const char *string);
 
 		/**
-		 * Transliterates cyrillic in UTF-32 string.
+		 * Transliterate a Cyrillic string into a UTF-32 string.
 		 *
-		 * The result has to be freed after use.
+		 * The result must be freed after usage.
 		 *
-		 * @param string String that should be converted
+		 * @param string The string to convert.
-		 * @param length Length of the string in bytes
+		 * @param length Length of the string in bytes.
 		 *
 		 * @return Transliterated string in UTF-32 (must be freed) or nullptr on fail.
 		 */

common/endian.h

@@ -30,22 +30,21 @@
  * @defgroup common_endian Endian conversions
  * @ingroup common
  *
- * @brief  Endian conversion and byteswap conversion functions and macros.
+ * @brief  Functions and macros for endian conversions and byteswap conversions.
  *
  * @details 
- *  SWAP_BYTES_??(a)      - inverse byte order
+ *  - SWAP_BYTES_??(a) - Reverse byte order
- *  SWAP_CONSTANT_??(a)   - inverse byte order, implemented as macro.
+ *  - SWAP_CONSTANT_??(a) - Reverse byte order, implemented as a macro.
- *                              Use with compiletime-constants only, the result will be a compiletime-constant aswell.
+ *                          Use with compile-time constants only, the result will be a compile-time constant as well.
- *                              Unlike most other functions these can be used for eg. switch-case labels
+ *                          Unlike most other functions, these can be used for e.g. switch-case labels.
- *
+ *  - READ_UINT??(a)   - Read native value from pointer @p a.
- *  READ_UINT??(a)        - read native value from pointer a
+ *  - READ_??_UINT??(a) - Read LE/BE value from pointer @p a and convert it to native.
- *  READ_??_UINT??(a)     - read LE/BE value from pointer a and convert it to native
+ *  - WRITE_??_UINT??(a, v) - Write a native value @p v to pointer @p a with LE/BE encoding.
- *  WRITE_??_UINT??(a, v) - write native value v to pointer a with LE/BE encoding
+ *  - TO_??_??(a) - Convert native value @p v to LE/BE.
- *  TO_??_??(a)           - convert native value v to LE/BE
+ *  - FROM_??_??(a) - Convert LE/BE value @p v to native.
- *  FROM_??_??(a)         - convert LE/BE value v to native
+ *  - CONSTANT_??_??(a) - Convert LE/BE value @p v to native, implemented as a macro.
- *  CONSTANT_??_??(a)     - convert LE/BE value v to native, implemented as macro.
+ *                        Use with compile-time constants only, the result will be a compile-time constant as well.
- *                              Use with compiletime-constants only, the result will be a compiletime-constant aswell.
+ *                        Unlike most other functions these, can be used for e.g. switch-case labels.
- *                              Unlike most other functions these can be used for eg. switch-case labels
  *
  * @{
  */
@@ -55,6 +54,10 @@
 #	error No endianness defined
 #endif
 
+/**
+ * Swap the bytes in a 64-bit word in order to convert LE encoded data to BE
+ * and vice versa. Use with compile-time constants only.
+ */
 #define SWAP_CONSTANT_64(a) \
 	((uint64)((((a) >> 56) & 0x000000FF) | \
 	          (((a) >> 40) & 0x0000FF00) | \
@@ -65,12 +68,20 @@
 	          (((a) & 0x0000FF00) << 40) | \
 	          (((a) & 0x000000FF) << 56) ))
 
+/**
+ * Swap the bytes in a 32-bit word in order to convert LE encoded data to BE
+ * and vice versa. Use with compile-time constants only.
+ */
 #define SWAP_CONSTANT_32(a) \
 	((uint32)((((a) >> 24) & 0x00FF) | \
 	          (((a) >>  8) & 0xFF00) | \
 	          (((a) & 0xFF00) <<  8) | \
 	          (((a) & 0x00FF) << 24) ))
 
+/**
+ * Swap the bytes in a 16-bit word in order to convert LE encoded data to BE
+ * and vice versa. Use with compile-time constants only.
+ */
 #define SWAP_CONSTANT_16(a) \
 	((uint16)((((a) >>  8) & 0x00FF) | \
 	          (((a) <<  8) & 0xFF00) ))
@@ -78,7 +89,7 @@
 
 
 /**
- * Swap the bytes in a 16 bit word in order to convert LE encoded data to BE
+ * Swap the bytes in a 16-bit word in order to convert LE encoded data to BE
  * and vice versa.
  */
 
@@ -106,7 +117,7 @@
 
 
 /**
- * Swap the bytes in a 32 bit word in order to convert LE encoded data to BE
+ * Swap the bytes in a 32-bit word in order to convert LE encoded data to BE
  * and vice versa.
  */
 
@@ -155,7 +166,7 @@
 #endif
 
 /**
- * Swap the bytes in a 64 bit word in order to convert LE encoded data to BE
+ * Swap the bytes in a 64-bit word in order to convert LE encoded data to BE
  * and vice versa.
  */
 
@@ -211,8 +222,8 @@
  * A wrapper macro used around four character constants, like 'DATA', to
  * ensure portability. Typical usage: MKTAG('D','A','T','A').
  *
- * Why is this necessary? The C/C++ standard does not define the endianess to
+ * This is required because the C/C++ standard does not define the endianess to
- * be used for character constants. Hence if one uses multi-byte character
+ * be used for character constants. Hence, if one uses multi-byte character
  * constants, a potential portability problem opens up.
  */
 #define MKTAG(a0,a1,a2,a3) ((uint32)((a3) | ((a2) << 8) | ((a1) << 16) | ((a0) << 24)))
@@ -223,8 +234,11 @@
  */
 #define MKTAG16(a0,a1) ((uint16)((a1) | ((a0) << 8)))
 
-// Functions for reading/writing native integers.
+/** @name Functions for reading and writing native integers
-// They also transparently handle the need for alignment.
+ *  @brief Functions for reading and writing native integer values.
+ *         They also transparently handle the need for alignment.
+ *  @{
+ */
 
 // Test for GCC >= 4.0. These implementations will automatically use
 // CPU-specific instructions for unaligned data when they are available (eg.
@@ -372,11 +386,14 @@
 		}
 
 #	endif
-
+/** @} */
 #endif
 
 
-//  Map Funtions for reading/writing BE/LE integers depending on native endianess
+/** @name  Map functions for reading/writing BE/LE integers depending on native endianess
+ * @{
+ */
+	 
 #if defined(SCUMM_LITTLE_ENDIAN)
 
 	#define READ_LE_UINT16(a) READ_UINT16(a)
@@ -411,8 +428,13 @@
 	#define TO_BE_64(a) SWAP_BYTES_64(a)
 	#define CONSTANT_LE_64(a) ((uint64)(a))
 	#define CONSTANT_BE_64(a) SWAP_CONSTANT_64(a)
+/** @} */
 
-// if the unaligned load and the byteswap take alot instructions its better to directly read and invert
+/** @name  Functions for directly reading/writing and inverting
+ *  @brief Use these in case the unaligned load and byteswap take
+ *         a lot of instructions.
+ * @{
+ */
 #	if defined(SCUMM_NEED_ALIGNMENT) && !defined(__mips__)
 
 		inline uint16 READ_BE_UINT16(const void *ptr) {
@@ -637,7 +659,7 @@ inline int32 READ_BE_INT32(const void *ptr) {
 inline void WRITE_BE_INT32(void *ptr, int32 value) {
 	WRITE_BE_UINT32(ptr, static_cast<uint32>(value));
 }
-
+/** @} */
 /** @} */
 
 #endif

common/error.h

@@ -37,43 +37,43 @@ namespace Common {
  */
 
 /**
- * Error codes which may be reported by plugins under various circumstances.
+ * Error codes that may be reported by plugins under various circumstances.
  *
  * @note Error names should follow the pattern k-NOUN/ACTION-CONDITION-Error.
- *       So kPathInvalidError would be correct, but these would not be:
+ *       So kPathInvalidError is correct, but the following are not:
  *       kInvalidPath, kPathInvalid, kPathIsInvalid, kInvalidPathError.
+ *
  * @todo Adjust all error codes to comply with these conventions.
  */
 enum ErrorCode {
-	kNoError = 0,				///< No error occurred
+	kNoError = 0,				///< No error occurred.
-	kNoGameDataFoundError,		///< Engine initialization: No game data was found in the specified location
+	kNoGameDataFoundError,		///< Engine initialization: No game data was found in the specified location.
-	kUnsupportedGameidError,	///< Engine initialization: Gameid not supported by this (Meta)Engine
+	kUnsupportedGameidError,	///< Engine initialization: Game ID not supported by this (Meta)Engine.
-	kUnsupportedColorMode,		///< Engine initialization: Engine does not support backend's color mode
+	kUnsupportedColorMode,		///< Engine initialization: Engine does not support backend's color mode.
-	kAudioDeviceInitFailed,		///< Engine initialization: Audio device initialization failed
+	kAudioDeviceInitFailed,		///< Engine initialization: Audio device initialization failed.
 
-	kReadPermissionDenied,		///< Unable to read data due to missing read permission
+	kReadPermissionDenied,		///< Unable to read data due to missing read permission.
-	kWritePermissionDenied,		///< Unable to write data due to missing write permission
+	kWritePermissionDenied,		///< Unable to write data due to missing write permission.
 
-	kPathDoesNotExist,			///< The specified path does not exist
+	kPathDoesNotExist,			///< The specified path does not exist.
-	kPathNotDirectory,			///< The specified path does not point to a directory
+	kPathNotDirectory,			///< The specified path does not point to a directory.
-	kPathNotFile,				///< The specified path does not point to a file
+	kPathNotFile,				///< The specified path does not point to a file.
 
-	kCreatingFileFailed,		///< Failed creating a (savestate) file
+	kCreatingFileFailed,		///< Failed creating a (savestate) file.
-	kReadingFailed,				///< Failed to read a file (permission denied?)
+	kReadingFailed,				///< Failed to read a file (permission denied?).
-	kWritingFailed,				///< Failure to write data -- disk full?
+	kWritingFailed,				///< Failure to write data - disk full?
 
-	// The following are used by --list-saves
+	/** Failed to find a MetaEnginePlugin. This should never happen, because all MetaEngines must always
+	 * be built into the executable, regardless if the engine plugins are present or not.
+     */
+	kMetaEnginePluginNotFound,
 
-	// Failed to find a MetaEnginePlugin. This should never happen, because all MetaEngines must always
+	kEnginePluginNotFound,		///< Failed to find an Engine plugin to handle target.
-	// be built into the executable, regardless if the engine plugins are present or not.
+	kEnginePluginNotSupportSaves,	///< The plugin does not support listing save states.
-	kMetaEnginePluginNotFound,	///< See comment above
 
-	kEnginePluginNotFound,		///< Failed to find a Engine plugin to handle target
+	kUserCanceled,			///< User has canceled the launching of the game.
-	kEnginePluginNotSupportSaves,	///< Failed if plugin does not support listing save states
 
-	kUserCanceled,			///< User has canceled the launching of the game
+	kUnknownError				///< Catch-all error, used if no other error code matches.
-
-	kUnknownError				///< Catch-all error, used if no other error code matches
 };
 
 /**
@@ -84,8 +84,8 @@ enum ErrorCode {
  */
 class Error {
 protected:
-	ErrorCode _code;
+	ErrorCode _code; /*!< Error code. */
-	String _desc;
+	String _desc;    /*!< Error description. */
 public:
 	/**
 	 * Construct a new Error with the specified error code and the default

common/events.h

@@ -70,12 +70,13 @@ enum EventType {
 	EVENT_QUIT = 10,
 	EVENT_SCREEN_CHANGED = 11,
 
-	/** The input devices have changed, input related configuration needs to be re-applied */
+	/** The input devices have changed, input-related configuration must be reapplied. */
 	EVENT_INPUT_CHANGED  = 35,
 
 	/**
-	 * The backend requests the agi engine's predictive dialog to be shown.
+	 * The backend requests the AGI engine's predictive dialog to be shown.
-	 * TODO: Fingolfin suggests that it would be of better value to expand
+	 * 
+     * @todo Fingolfin suggests that it would be of better value to expand
 	 * on this notion by generalizing its use. For example the backend could
 	 * use events to ask for the save game dialog or to pause the engine.
 	 * An associated enumerated type can accomplish this.
@@ -107,14 +108,14 @@ enum EventType {
 	 * Additional mouse events, details in Event::mouse.
 	 *
 	 * Note that X1 and X2 are usually back and forward, however
-	 * this can't be guaranteed on all platforms.
+	 * this cannot be guaranteed on all platforms.
 	 */
 	EVENT_X1BUTTONDOWN = 30,
 	EVENT_X1BUTTONUP = 31,
 	EVENT_X2BUTTONDOWN = 32,
 	EVENT_X2BUTTONUP = 33,
 
-	/** ScummVM has gained or lost focus */
+	/** ScummVM has gained or lost focus. */
 	EVENT_FOCUS_GAINED = 36,
 	EVENT_FOCUS_LOST = 37
 };
@@ -123,15 +124,15 @@ const int16 JOYAXIS_MIN = -32768;
 const int16 JOYAXIS_MAX = 32767;
 
 /**
- * Data structure for joystick events
+ * Data structure for joystick events.
  */
 struct JoystickState {
-	/** The axis for EVENT_JOYAXIS_MOTION events */
+	/** The axis for EVENT_JOYAXIS_MOTION events. */
 	byte axis;
-	/** The new axis position for EVENT_JOYAXIS_MOTION events */
+	/** The new axis position for EVENT_JOYAXIS_MOTION events. */
 	int16 position;
 	/**
-	 * The button index for EVENT_JOYBUTTON_DOWN/UP events
+	 * The button index for EVENT_JOYBUTTON_DOWN/UP events.
 	 *
 	 * Some of the button indices match well-known game controller
 	 * buttons. See JoystickButton.
@@ -142,7 +143,7 @@ struct JoystickState {
 };
 
 /**
- *  The list of named buttons available from a joystick
+ *  The list of named buttons available from a joystick.
  */
 enum JoystickButton {
 	JOYSTICK_BUTTON_A,
@@ -163,7 +164,7 @@ enum JoystickButton {
 };
 
 /**
- *  The list of named axes available from a joystick
+ *  The list of named axes available from a joystick.
  */
 enum JoystickAxis {
 	JOYSTICK_AXIS_LEFT_STICK_X,
@@ -175,7 +176,7 @@ enum JoystickAxis {
 };
 
 /**
- *  The list named buttons available from a mouse
+ *  The list named buttons available from a mouse.
  */
 enum MouseButton {
 	MOUSE_BUTTON_LEFT   = 0,
@@ -186,7 +187,7 @@ enum MouseButton {
 	MOUSE_BUTTON_X1     = 5,
 	MOUSE_BUTTON_X2     = 6
 };
-
+/** Used by @ref ArtificialEventSource. */
 typedef uint32 CustomEventType;
 
 /**
@@ -199,7 +200,7 @@ struct Event {
 	EventType type;
 
 	/**
-	 * True if this is a key down repeat event.
+	 * True if this is a key-down repeat event.
 	 *
 	 * Only valid for EVENT_KEYDOWN events.
 	 */
@@ -214,14 +215,15 @@ struct Event {
 	/**
 	 * The mouse coordinates, in virtual screen coordinates. Only valid
 	 * for mouse events.
-	 * Virtual screen coordinates means: the coordinate system of the
+	 * 'Virtual screen coordinates' refers to the coordinate system of the
 	 * screen area as defined by the most recent call to initSize().
 	 */
 	Point mouse;
-
+    
+	/** Refers to an event generated by @ref ArtificialEventSource. */
 	CustomEventType customType;
 
-	/* The path of the file or directory dragged to the ScummVM window */
+	/** The path of the file or directory dragged to the ScummVM window. */
 	Common::String path;
 
 	/**
@@ -240,51 +242,52 @@ struct Event {
 };
 
 /**
- * Determinates whether an event is a mouse event
+ * Determine whether an event is a mouse event.
  *
- * Mouse events have valid mouse coordinates
+ * Mouse events have valid mouse coordinates.
  */
 bool isMouseEvent(const Event &event);
 
 /**
  * A source of Events.
  *
- * An example for this is OSystem, it provides events created by the system
+ * An example for this is OSystem, which provides events created by the system
- * and or user.
+ * and/or user.
  */
 class EventSource {
 public:
 	virtual ~EventSource();
 
 	/**
-	 * Queries a event from the source.
+	 * Query an event from the source.
 	 *
-	 * @param	event 	a reference to the event struct, where the event should be stored.
+	 * @param	event 	Reference to the event struct where the event should be stored.
-	 * @return	true if an event was polled, false otherwise.
+	 * @retval	true If an event was polled, false otherwise.
 	 */
 	virtual bool pollEvent(Event &event) = 0;
 
 	/**
-	 * Checks whether events from this source are allowed to be mapped.
+	 * Check whether events from this source are allowed to be mapped.
 	 *
 	 * Possible event sources not allowing mapping are: the event recorder/player and/or
 	 * the EventManager, which allows user events to be pushed.
 	 *
-	 * By default we allow mapping for every event source.
+	 * By default, mapping is allowed for every event source.
 	 */
 	virtual bool allowMapping() const { return true; }
 };
 
 /**
- * An artificial event source. This is class is used as an event source, which is
+ * An artificial event source. This class is used as an event source, which is
- * made up by client specific events.
+ * made up by client-specific events.
  *
- * Example usage cases for this are the Keymapper or the DefaultEventManager.
+ * Example use cases for this are the Keymapper or the DefaultEventManager.
  */
 class ArtificialEventSource : public EventSource {
 protected:
 	Queue<Event> _artificialEventQueue;
 public:
+    /** Put the specified event into the queue. */
 	void addEvent(const Event &ev) {
 		_artificialEventQueue.push(ev);
 	}
@@ -299,44 +302,44 @@ public:
 	}
 
 	/**
-	 * By default an artificial event source prevents its events
+	 * By default, an artificial event source prevents its events
 	 * from being mapped.
 	 */
 	virtual bool allowMapping() const { return false; }
 };
 
 /**
- * Object which catches and processes Events.
+ * Object that catches and processes Events.
  *
- * An example for this is the Engine object, it is catching events and processing them.
+ * An example for this is the Engine object - it catches events and processes them.
  */
 class EventObserver {
 public:
 	virtual ~EventObserver();
 
 	/**
-	 * Notifies the observer of an incoming event.
+	 * Notify the observer of an incoming event.
 	 *
-	 * An observer is supposed to eat the event, with returning true, when
+	 * An observer is supposed to 'eat' the event, with returning true, when
 	 * it wants to prevent other observers from receiving the event.
 	 * A usage example here is the keymapper:
 	 * If it processes an Event, it should 'eat' it and create a new
 	 * event, which the EventDispatcher will then catch.
 	 *
-	 * @param   event   the event, which is incoming.
+	 * @param   event   The event that is incoming.
-	 * @return  true if the event should not be passed to other observers,
+	 * @retval  true If the event should not be passed to other observers,
 	 *          false otherwise.
 	 */
 	virtual bool notifyEvent(const Event &event) = 0;
 
 	/**
-	 * Notifies the observer of pollEvent() query.
+	 * Notify the observer of pollEvent() query.
 	 */
 	virtual void notifyPoll() { }
 };
 
 /**
- * A event mapper, which will map events to others.
+ * A event mapper that maps events to others.
  *
  * An example for this is the Keymapper.
  */
@@ -345,20 +348,20 @@ public:
 	virtual ~EventMapper();
 
 	/**
-	 * Map an incoming event to one or more action events
+	 * Map an incoming event to one or more action events.
 	 */
 	virtual List<Event> mapEvent(const Event &ev) = 0;
 };
 
 /**
- * Dispatches events from various sources to various observers.
+ * Dispatch events from various sources to various observers.
  *
- * EventDispatcher is using a priority based approach. Observers
+ * EventDispatcher uses a priority-based approach. Observers
- * with higher priority will be notified before observers with
+ * with higher priority are notified before observers with
- * lower priority. Because of the possibility that oberservers
+ * lower priority. Note that observers might 'eat' events,
- * might 'eat' events, not all observers might be notified.
+ * and thus not all observers might be notified.
  *
- * Another speciality is the support for a event mapper, which
+ * Another speciality is the support for an event mapper that
  * will catch events and create new events out of them. This
  * mapper will be processed before an event is sent to the
  * observers.
@@ -369,7 +372,7 @@ public:
 	~EventDispatcher();
 
 	/**
-	 * Tries to catch events from the registered event
+	 * Attempt to catch events from the registered event
 	 * sources and dispatch them to the observers.
 	 *
 	 * This dispatches *all* events the sources offer.
@@ -383,32 +386,32 @@ public:
 	void clearEvents();
 
 	/**
-	 * Registers an event mapper with the dispatcher.
+	 * Register an event mapper with the dispatcher.
 	 */
 	void registerMapper(EventMapper *mapper);
 
 	/**
-	 * Registers a new EventSource with the Dispatcher.
+	 * Register a new EventSource with the Dispatcher.
 	 */
 	void registerSource(EventSource *source, bool autoFree);
 
 	/**
-	 * Unregisters a EventSource.
+	 * Unregister an EventSource.
 	 *
 	 * This takes the "autoFree" flag passed to registerSource into account.
 	 */
 	void unregisterSource(EventSource *source);
 
 	/**
-	 * Registers a new EventObserver with the Dispatcher.
+	 * Register a new EventObserver with the Dispatcher.
 	 *
-	 * @param listenPolls if set, then all pollEvent() calls are passed to observer
+	 * @param listenPolls If set, then all pollEvent() calls are passed to the observer.
-	 *                    currently it is used by keyMapper
+	 *                    Currently, it is used by keyMapper.
 	 */
 	void registerObserver(EventObserver *obs, uint priority, bool autoFree, bool listenPolls = false);
 
 	/**
-	 * Unregisters a EventObserver.
+	 * Unregister an EventObserver.
 	 *
 	 * This takes the "autoFree" flag passed to registerObserver into account.
 	 */
@@ -444,7 +447,7 @@ class Keymapper;
 /**
  * The EventManager provides user input events to the client code.
  * In addition, it keeps track of the state of various input devices,
- * like keys, mouse position and buttons.
+ * like keys, mouse position, and buttons.
  */
 class EventManager : NonCopyable {
 public:
@@ -458,28 +461,28 @@ public:
 
 	/**
 	 * Initialize the event manager.
-	 * @note	called after graphics system has been set up
+	 * @note	Called after graphics system has been set up.
 	 */
 	virtual void init() {}
 
 	/**
 	 * Get the next event in the event queue.
-	 * @param event	point to an Event struct, which will be filled with the event data.
+	 * @param event	Point to an Event struct, which will be filled with the event data.
-	 * @return true if an event was retrieved.
+	 * @retval true If an event was retrieved.
 	 */
 	virtual bool pollEvent(Event &event) = 0;
 
 	/**
-	 * Pushes a "fake" event into the event queue
+	 * Push a "fake" event into the event queue.
 	 */
 	virtual void pushEvent(const Event &event) = 0;
 
 	/**
-	 * Purges all unprocessed mouse events already in the event queue.
+	 * Purge all unprocessed mouse events already in the event queue.
 	 */
 	virtual void purgeMouseEvents() = 0;
 
-	/** Return the current mouse position */
+	/** Return the current mouse position. */
 	virtual Point getMousePos() const = 0;
 
 	/**
@@ -489,17 +492,16 @@ public:
 	 */
 	virtual int getButtonState() const = 0;
 
-	/** Get a bitmask with the current modifier state */
+	/** Get a bitmask with the current modifier state. */
 	virtual int getModifierState() const = 0;
 
 	/**
-	 * Should the application terminate? Set to true if we
+	 * Whether the application should terminate. Set to true if EVENT_QUIT was received.
-	 * received an EVENT_QUIT.
 	 */
 	virtual int shouldQuit() const = 0;
 
 	/**
-	 * Should we return to the launcher?
+	 * Whether to return to the launcher.
 	 */
 	virtual int shouldReturnToLauncher() const = 0;
 
@@ -518,30 +520,31 @@ public:
 
 	// TODO: Consider removing OSystem::getScreenChangeID and
 	// replacing it by a generic getScreenChangeID method here
-
+    /** Return the @ref Keymapper object. */	
 	virtual Keymapper *getKeymapper() = 0;
+	/** Return the global @ref Keymap object. */
 	virtual Keymap *getGlobalKeymap() = 0;
 
 	enum {
 		/**
-		 * Priority of the event manager, for now it's lowest since it eats
+		 * Priority of the event manager. For now, it is lowest since it eats
-		 * *all* events, we might to change that in the future though.
+		 * *all* events. This might be changed in the future though.
 		 */
 		kEventManPriority = 0,
 		/**
-		 * Priority of the event recorder. It has to go after event manager
+		 * Priority of the event recorder. It must go after the event manager
-		 * in order to record events generated by it
+		 * in order to record events generated by it.
 		 */
 		kEventRecorderPriority = 1,
 		/**
-		 * Priority of the remap dialog. It has to go first to capture all
+		 * Priority of the remap dialog. It must go first to capture all
 		 * the events before they are consumed by other observers.
 		 */
 		kEventRemapperPriority = 999
 	};
 
 	/**
-	 * Returns the underlying EventDispatcher.
+	 * Return the underlying EventDispatcher.
 	 */
 	EventDispatcher *getEventDispatcher() { return &_dispatcher; }
 
@@ -550,7 +553,7 @@ protected:
 };
 
 /**
- * Wrap an event source so the key down events are repeated while
+ * Wrap an event source so the key-down events are repeated while
  * keys are held down.
  *
  * Does not take ownership of the wrapped EventSource.

common/fft.h

@@ -46,10 +46,10 @@ namespace Common {
 class CosineTable;
 
 /**
- * (Inverse) Fast Fourier Transform
+ * (Inverse) Fast Fourier Transform.
  *
  * Used in engines:
- *  - scumm
+ *  - SCUMM
  */
 class FFT {
 public:
@@ -58,10 +58,10 @@ public:
 
 	const uint16 *getRevTab() const;
 
-	/** Do the permutation needed BEFORE calling calc(). */
+	/** Perform the permutation needed BEFORE calling calc(). */
 	void permute(Complex *z);
 
-	/** Do a complex FFT.
+	/** Perform a complex FFT.
 	 *
 	 *  The input data must be permuted before.
 	 *  No 1.0/sqrt(n) normalization is done.

common/file.h

@@ -43,7 +43,7 @@ namespace Common {
 class Archive;
 
 /**
- * TODO: vital to document this core class properly!!! For both users and implementors
+ * @todo vital to document this core class properly!!! For both users and implementors
  */
 class File : public SeekableReadStream, public NonCopyable {
 protected:
@@ -58,52 +58,52 @@ public:
 	virtual ~File();
 
 	/**
-	 * Checks if a given file exists in any of the current default paths,
+	 * Check if a given file exists in any of the current default paths,
 	 * as defined by SearchMan.
 	 *
-	 * @param	filename	the file to check for
+	 * @param	filename	The file to check for.
-	 * @return	true if the file exists, false otherwise
+	 * @return	True if the file exists, false otherwise.
 	 */
 	static bool exists(const String &filename);
 
 	/**
-	 * Try to open the file with the given filename, by searching SearchMan.
+	 * Try to open the file with the given file name, by searching SearchMan.
-	 * @note Must not be called if this file already is open (i.e. if isOpen returns true).
+	 * @note Must not be called if this file is already open (i.e. if isOpen returns true).
 	 *
-	 * @param	filename	the name of the file to open
+	 * @param	filename	Name of the file to open.
-	 * @return	true if file was opened successfully, false otherwise
+	 * @return	True if the file was opened successfully, false otherwise.
 	 */
 	virtual bool open(const String &filename);
 
 	/**
-	 * Try to open the file with the given filename from within the given archive.
+	 * Try to open the file with the given file name from within the given archive.
-	 * @note Must not be called if this file already is open (i.e. if isOpen returns true).
+	 * @note Must not be called if this file is already open (i.e. if isOpen returns true).
 	 *
-	 * @param	filename	the name of the file to open
+	 * @param	filename	Name of the file to open.
-	 * @param	archive		the archive in which to search for the file
+	 * @param	archive		Archive in which to search for the file.
-	 * @return	true if file was opened successfully, false otherwise
+	 * @return	True if the file was opened successfully, false otherwise.
 	 */
 	virtual bool open(const String &filename, Archive &archive);
 
 	/**
-	 * Try to open the file corresponding to the give node. Will check whether the
+	 * Try to open the file corresponding to the given node. Will check whether the
 	 * node actually refers to an existing file (and not a directory), and handle
 	 * those cases gracefully.
 	 * @note Must not be called if this file already is open (i.e. if isOpen returns true).
 	 *
-	 * @param   node        the node to consider.
+	 * @param   node        The node to consider.
-	 * @return	true if file was opened successfully, false otherwise
+	 * @return	True if the file was opened successfully, false otherwise.
 	 */
 	virtual bool open(const FSNode &node);
 
 	/**
-	 * Try to 'open' the given stream. That is, we just wrap around it, and if stream
+	 * Try to 'open' the given stream. That is, wrap around it, and if the stream
-	 * is a NULL pointer, we gracefully treat this as if opening failed.
+	 * is a NULL pointer, gracefully treat this as if opening failed.
 	 * @note Must not be called if this file already is open (i.e. if isOpen returns true).
 	 *
-	 * @param	stream		a pointer to a SeekableReadStream, or 0
+	 * @param	stream		Pointer to a SeekableReadStream, or 0.
-	 * @param	name		a string describing the 'file' corresponding to stream
+	 * @param	name		String describing the 'file' corresponding to the stream.
-	 * @return	true if stream was non-zero, false otherwise
+	 * @return	True if the stream was non-zero, false otherwise.
 	 */
 	virtual bool open(SeekableReadStream *stream, const String &name);
 
@@ -113,39 +113,39 @@ public:
 	virtual void close();
 
 	/**
-	 * Checks if the object opened a file successfully.
+	 * Check if the object opened a file successfully.
 	 *
-	 * @return: true if any file is opened, false otherwise.
+	 * @return True if any file is opened, false otherwise.
 	 */
 	bool isOpen() const;
 
 	/**
-	 * Returns the filename of the opened file for debugging purposes.
+	 * Return the file name of the opened file for debugging purposes.
 	 *
-	 * @return: the filename
+	 * @return The file name of the opened file.
 	 */
 	const char *getName() const { return _name.c_str(); }
 
-	bool err() const override;	// implement abstract Stream method
+	bool err() const override;	/*!< Implement abstract Stream method. */
-	void clearErr() override;	// implement abstract Stream method
+	void clearErr() override;	/*!< Implement abstract Stream method. */
-	bool eos() const override;	// implement abstract SeekableReadStream method
+	bool eos() const override;	/*!< Implement abstract SeekableReadStream method. */
 
-	int32 pos() const override;	// implement abstract SeekableReadStream method
+	int32 pos() const override;	 /*!< Implement abstract SeekableReadStream method. */
-	int32 size() const override;	// implement abstract SeekableReadStream method
+	int32 size() const override; /*!< Implement abstract SeekableReadStream method. */
-	bool seek(int32 offs, int whence = SEEK_SET) override;	// implement abstract SeekableReadStream method
+	bool seek(int32 offs, int whence = SEEK_SET) override;	/*!< Implement abstract SeekableReadStream method. */
-	uint32 read(void *dataPtr, uint32 dataSize) override;	// implement abstract SeekableReadStream method
+	uint32 read(void *dataPtr, uint32 dataSize) override;	/*!< Implement abstract SeekableReadStream method. */
 };
 
 
 /**
- * TODO: document this class
+ * @todo Document this class
  *
  * Some design ideas:
  *  - automatically drop all files into dumps/ dir? Might not be desired in all cases
  */
 class DumpFile : public SeekableWriteStream, public NonCopyable {
 protected:
-	/** File handle to the actual file; 0 if no file is open. */
+	/** File handle to the actual file. 0 if no file is open. */
 	WriteStream *_handle;
 
 public:
@@ -158,9 +158,9 @@ public:
 	virtual void close();
 
 	/**
-	 * Checks if the object opened a file successfully.
+	 * Check if the object opened a file successfully.
 	 *
-	 * @return: true if any file is opened, false otherwise.
+	 * @return True if any file is opened, false otherwise.
 	 */
 	bool isOpen() const;
 

common/frac.h

@@ -35,8 +35,8 @@
  */
 
 /**
- * The precision of the fractional (fixed point) type we define below.
+ * The precision of the fractional (fixed-point) type that is defined below.
- * Normally you should never have to modify this value.
+ * Normally, you should never need to modify this value.
  */
 enum {
 	FRAC_BITS = 16,

common/fs.h

@@ -48,20 +48,20 @@ class SeekableReadStream;
 class WriteStream;
 
 /**
- * List of multiple file system nodes. E.g. the contents of a given directory.
+ * List of multiple file system nodes. For example, the contents of a given directory.
- * This is subclass instead of just a typedef so that we can use forward
+ * This is a subclass instead of just a typedef so that forward declarations
- * declarations of it in other places.
+ * of it can be used in other places.
  */
 class FSList : public Array<FSNode> {};
 
 /**
  * FSNode, short for "File System Node", provides an abstraction for file
- * paths, allowing for portable file system browsing. This means for example,
+ * paths, allowing for portable file system browsing. This means, for example,
  * that multiple or single roots have to be supported (compare Unix with a
  * single root, Windows with multiple roots C:, D:, ...).
  *
  * To this end, we abstract away from paths; implementations can be based on
- * paths (and it's left to them whether / or \ or : is the path separator :-);
+ * paths (and it is left to them whether '/', '\', or ':' is the path separator)
  * but it is also possible to use inodes or vrefs (MacOS 9) or anything else.
  */
 class FSNode : public ArchiveMember {
@@ -69,7 +69,7 @@ private:
 	friend class ::AbstractFSNode;
 	SharedPtr<AbstractFSNode>	_realNode;
 	/**
-	 * Construct a FSNode from a backend's AbstractFSNode implementation.
+	 * Construct an FSNode from a backend's AbstractFSNode implementation.
 	 *
 	 * @param realNode Pointer to a heap allocated instance. FSNode will take
 	 *                 ownership of the pointer.
@@ -87,7 +87,7 @@ public:
 	};
 
 	/**
-	 * Create a new pathless FSNode. Since there's no path associated
+	 * Create a new pathless FSNode. Since there is no path associated
 	 * with this node, path-related operations (i.e. exists(), isDirectory(),
 	 * getPath()) will always return false or raise an assertion.
 	 */
@@ -97,9 +97,9 @@ public:
 	 * Create a new FSNode referring to the specified path. This is
 	 * the counterpart to the path() method.
 	 *
-	 * If path is empty or equals ".", then a node representing the "current
+	 * If the path is empty or equals ".", then a node representing the "current
 	 * directory" will be created. If that is not possible (since e.g. the
-	 * operating system doesn't support the concept), some other directory is
+	 * operating system does not support the concept), some other directory is
 	 * used (usually the root directory).
 	 */
 	explicit FSNode(const String &path);
@@ -113,9 +113,9 @@ public:
 	bool operator<(const FSNode& node) const;
 
 	/**
-	 * Indicates whether the object referred by this node exists in the filesystem or not.
+	 * Indicate whether the object referred by this node exists in the file system or not.
 	 *
-	 * @return bool true if the node exists, false otherwise.
+	 * @return True if the node exists, false otherwise.
 	 */
 	bool exists() const;
 
@@ -131,10 +131,10 @@ public:
 	 *       this should affect what exists/isDirectory/isReadable/isWritable return
 	 *       for existing nodes. However, this is not the case for many existing
 	 *       FSNode implementations. Either fix those, or document that FSNodes
-	 *       can become 'stale'...
+	 *       can become 'stale'.
 	 *
-	 * @param name	the name of a child of this directory
+	 * @param name	Name of a child of this directory.
-	 * @return the node referring to the child with the given name
+	 * @return The node referring to the child with the given name.
 	 */
 	FSNode getChild(const String &name) const;
 
@@ -142,40 +142,40 @@ public:
 	 * Return a list of all child nodes of this directory node. If called on a node
 	 * that does not represent a directory, false is returned.
 	 *
-	 * @return true if successful, false otherwise (e.g. when the directory does not exist).
+	 * @return True if successful, false otherwise (e.g. when the directory does not exist).
 	 */
 	bool getChildren(FSList &fslist, ListMode mode = kListDirectoriesOnly, bool hidden = true) const;
 
 	/**
-	 * Return a human readable string for this node, usable for display (e.g.
+	 * Return a human-readable string for this node, usable for display (e.g.
 	 * in the GUI code). Do *not* rely on it being usable for anything else,
-	 * like constructing paths!
+	 * like constructing paths.
 	 *
-	 * @return the display name
+	 * @return The display name.
 	 */
 	virtual String getDisplayName() const;
 
 	/**
 	 * Return a string representation of the name of the file. This can be
 	 * used e.g. by detection code that relies on matching the name of a given
-	 * file. But it is *not* suitable for use with fopen / File::open, nor
+	 * file. However, it is *not* suitable for use with fopen / File::open, nor
 	 * should it be archived.
 	 *
-	 * @return the file name
+	 * @return The file name.
 	 */
 	virtual String getName() const;
 
 	/**
-	 * Return a string representation of the file which is suitable for
+	 * Return a string representation of the file that is suitable for
 	 * archiving (i.e. writing to the config file). This will usually be a
 	 * 'path' (hence the name of the method), but can be anything that meets
-	 * the above criterions. What a 'path' is differs greatly from system to
+	 * the above criteria. What a 'path' is differs greatly from system to
-	 * system anyway.
+	 * system.
 	 *
 	 * @note Do not assume that this string contains (back)slashes or any
 	 *       other kind of 'path separators'.
 	 *
-	 * @return the 'path' represented by this filesystem node
+	 * @return The 'path' represented by this file system node.
 	 */
 	String getPath() const;
 
@@ -186,7 +186,7 @@ public:
 	FSNode getParent() const;
 
 	/**
-	 * Indicates whether the node refers to a directory or not.
+	 * Indicate whether the node refers to a directory or not.
 	 *
 	 * @todo Currently we assume that a node that is not a directory
 	 * automatically is a file (ignoring things like symlinks or pipes).
@@ -197,7 +197,7 @@ public:
 	bool isDirectory() const;
 
 	/**
-	 * Indicates whether the object referred by this node can be read from or not.
+	 * Indicate whether the object referred by this node can be read from or not.
 	 *
 	 * If the node refers to a directory, readability implies being able to read
 	 * and list the directory entries.
@@ -205,63 +205,63 @@ public:
 	 * If the node refers to a file, readability implies being able to read the
 	 * contents of the file.
 	 *
-	 * @return true if the object can be read, false otherwise.
+	 * @return True if the object can be read, false otherwise.
 	 */
 	bool isReadable() const;
 
 	/**
-	 * Indicates whether the object referred by this node can be written to or not.
+	 * Indicate whether the object referred by this node can be written to or not.
 	 *
 	 * If the node refers to a directory, writability implies being able to modify
-	 * the directory entry (i.e. rename the directory, remove it or write files inside of it).
+	 * the directory entry (i.e. rename the directory, remove it, or write files inside of it).
 	 *
 	 * If the node refers to a file, writability implies being able to write data
 	 * to the file.
 	 *
-	 * @return true if the object can be written to, false otherwise.
+	 * @return True if the object can be written to, false otherwise.
 	 */
 	bool isWritable() const;
 
 	/**
-	 * Creates a SeekableReadStream instance corresponding to the file
+	 * Create a SeekableReadStream instance corresponding to the file
 	 * referred by this node. This assumes that the node actually refers
 	 * to a readable file. If this is not the case, 0 is returned.
 	 *
-	 * @return pointer to the stream object, 0 in case of a failure
+	 * @return Pointer to the stream object, 0 in case of a failure.
 	 */
 	virtual SeekableReadStream *createReadStream() const;
 
 	/**
-	 * Creates a WriteStream instance corresponding to the file
+	 * Create a WriteStream instance corresponding to the file
 	 * referred by this node. This assumes that the node actually refers
 	 * to a readable file. If this is not the case, 0 is returned.
 	 *
-	 * @return pointer to the stream object, 0 in case of a failure
+	 * @return Pointer to the stream object, 0 in case of a failure.
 	 */
 	WriteStream *createWriteStream() const;
 
 	/**
-	 * Creates a directory referred by this node. This assumes that this
+	 * Create a directory referred by this node. This assumes that this
-	 * node refers to non-existing directory. If this is not the case,
+	 * node refers to a non-existing directory. If this is not the case,
 	 * false is returned.
 	 *
-	 * @return true if the directory was created, false otherwise.
+	 * @return True if the directory was created, false otherwise.
 	 */
 	bool createDirectory() const;
 };
 
 /**
- * FSDirectory models a directory tree from the filesystem and allows users
+ * FSDirectory models a directory tree from the file system and allows users
  * to access it through the Archive interface. Searching is case-insensitive,
- * since the intended goal is supporting retrieval of game data.
+ * since the intended goal is to support retrieval of game data.
  *
  * FSDirectory can represent a single directory, or a tree with specified depth,
  * depending on the value passed to the 'depth' parameter in the constructors.
- * In the default mode, filenames are cached with their relative path,
+ * In the default mode, file names are cached with their relative path,
  * with elements separated by slashes, e.g.:
- *
+ * @code
  * c:\my\data\file.ext
- *
+ * @endcode
  * would be cached as 'data/file.ext' if FSDirectory was created on 'c:/my' with
  * depth > 1. If depth was 1, then the 'data' subdirectory would have been
  * ignored, instead.
@@ -269,24 +269,27 @@ public:
  * underlying file system.
  *
  * Relative paths can be specified when calling matching functions like createReadStreamForMember(),
- * hasFile(), listMatchingMembers() and listMembers(). Please see the function
+ * hasFile(), listMatchingMembers(), and listMembers(). See the function-specific
- * specific comments for more information.
+ * documentation for more information.
  *
  * If the 'flat' argument to the constructor is true, files in subdirectories
- * are cached without the relative path, so in the example above
+ * are cached without the relative path, so in the following example:
- * c:\my\data\file.ext would be cached as file.ext.
+ * @code
+ * c:\my\data\file.ext
+ * @endcode
+ * would be cached as 'file.ext'.
  *
  * When the 'ignoreClashes' argument to the constructor is true, name clashes are
- * expected by the engine. It means that files which clash should be identical and
+ * expected by the engine. It means that files that clash should be identical and
- * getSubDirectory shouldn't be used on clashing directories. This flag is useful
+ * getSubDirectory should not be used on clashing directories. This flag is useful
- * in flat mode when there are directories with same name at different places in the
+ * in flat mode when there are directories with the same name at different places in the
- * tree whose name isn't relevant for the engine code.
+ * tree whose name is not relevant for the engine code.
  *
- * Client code can customize cache by using the constructors with the 'prefix'
+ * Client code can customize the cache by using constructors with the 'prefix'
  * parameter. In this case, the prefix is prepended to each entry in the cache,
  * and effectively treated as a 'virtual' parent subdirectory. FSDirectory adds
- * a trailing slash to prefix if needed. Following on with the previous example
+ * a trailing slash to the prefix if needed. Following on with the previous example
- * and using 'your' as prefix, the cache entry would have been 'your/data/file.ext'.
+ * and using 'your' as a prefix, the cache entry would have been 'your/data/file.ext'.
  * This is done both in non-flat and flat mode.
  *
  */
@@ -318,64 +321,74 @@ class FSDirectory : public Archive {
 public:
 	/**
 	 * Create a FSDirectory representing a tree with the specified depth. Will result in an
-	 * unbound FSDirectory if name is not found on the filesystem or if the node is not a
+	 * unbound FSDirectory if name is not found in the file system or if the node is not a
 	 * valid directory.
 	 */
 	FSDirectory(const String &name, int depth = 1, bool flat = false,
 	            bool ignoreClashes = false, bool includeDirectories = false);
+	/**
+	 * @overload
+	 */
 	FSDirectory(const FSNode &node, int depth = 1, bool flat = false,
 	            bool ignoreClashes = false, bool includeDirectories = false);
 
 	/**
 	 * Create a FSDirectory representing a tree with the specified depth. The parameter
-	 * prefix is prepended to the keys in the cache. See class comment.
+	 * prefix is prepended to the keys in the cache. See @ref FSDirectory.
 	 */
 	FSDirectory(const String &prefix, const String &name, int depth = 1,
 	            bool flat = false, bool ignoreClashes = false, bool includeDirectories = false);
+	/**
+	 * @overload
+	 */
 	FSDirectory(const String &prefix, const FSNode &node, int depth = 1,
 	            bool flat = false, bool ignoreClashes = false, bool includeDirectories = false);
 
 	virtual ~FSDirectory();
 
 	/**
-	 * This return the underlying FSNode of the FSDirectory.
+	 * Return the underlying FSNode of the FSDirectory.
 	 */
 	FSNode getFSNode() const;
 
 	/**
-	 * Create a new FSDirectory pointing to a sub directory of the instance. See class comment
+	 * Create a new FSDirectory pointing to a subdirectory of the instance.
-	 * for an explanation of the prefix parameter.
+	 * @return A new FSDirectory instance.
-	 * @return a new FSDirectory instance
 	 */
 	FSDirectory *getSubDirectory(const String &name, int depth = 1, bool flat = false,
 	                             bool ignoreClashes = false);
+	/**
+	 * Create a new FSDirectory pointing to a subdirectory of the instance. See FSDirectory
+	 * for an explanation of the prefix parameter.
+	 * @return A new FSDirectory instance.
+	 */
 	FSDirectory *getSubDirectory(const String &prefix, const String &name, int depth = 1,
 	                             bool flat = false, bool ignoreClashes = false);
 
 	/**
-	 * Checks for existence in the cache. A full match of relative path and filename is needed
+	 * Check for the existence of a file in the cache. A full match of relative path and file name
-	 * for success.
+	 * is needed for success.
 	 */
 	virtual bool hasFile(const String &name) const;
 
 	/**
-	 * Returns a list of matching file names. Pattern can use GLOB wildcards.
+	 * Return a list of matching file names. Pattern can use GLOB wildcards.
 	 */
 	virtual int listMatchingMembers(ArchiveMemberList &list, const String &pattern) const;
 
 	/**
-	 * Returns a list of all the files in the cache.
+	 * Return a list of all the files in the cache.
 	 */
 	virtual int listMembers(ArchiveMemberList &list) const;
 
 	/**
-	 * Get a ArchiveMember representation of the specified file. A full match of relative
+	 * Get an ArchiveMember representation of the specified file. A full match of relative
-	 * path and filename is needed for success.
+	 * path and file name is needed for success.
 	 */
 	virtual const ArchiveMemberPtr getMember(const String &name) const;
 
 	/**
-	 * Open the specified file. A full match of relative path and filename is needed
+	 * Open the specified file. A full match of relative path and file name is needed
 	 * for success.
 	 */
 	virtual SeekableReadStream *createReadStreamForMember(const String &name) const;

common/gui_options.h

@@ -111,8 +111,8 @@ String parseGameGUIOptions(const String &str);
 const String getGameGUIOptionsDescription(const String &options);
 
 /**
- * Updates the GUI options of the current config manager
+ * Update the GUI options of the current config manager
- * domain, when they differ to the ones passed as
+ * domain when they differ to the ones passed as
  * parameter.
  */
 void updateGameGUIOptions(const String &options, const String &langOption);

common/hash-ptr.h

@@ -37,7 +37,7 @@ namespace Common {
  */
 
 /**
- * Partial specialization of the Hash functor to be able to use pointers as HashMap keys
+ * Partial specialization of the Hash functor allowing to use pointers as HashMap keys.
  */
 template<typename T>
 struct Hash<T *> {

common/hashmap.h

@@ -26,19 +26,16 @@
 #ifndef COMMON_HASHMAP_H
 #define COMMON_HASHMAP_H
 
-/**
+// Enable the following #define if you want to check how many collisions the
- * @def DEBUG_HASH_COLLISIONS
+// code produces (many collisions indicate either a bad hash function, or a
- * Enable the following #define if you want to check how many collisions the
+// hash table that is too small).
- * code produces (many collisions indicate either a bad hash function, or a
+ 
- * hash table that is too small).
- */
 //#define DEBUG_HASH_COLLISIONS
 
 /**
- * @def USE_HASHMAP_MEMORY_POOL
  * Enable the following define to let HashMaps use a memory pool for the
- nodes they contain. * This increases memory usage, but also can improve
+ * nodes they contain. This increases memory usage, but can also improve
- speed quite a bit.
+ * speed quite a bit.
  */
 #define USE_HASHMAP_MEMORY_POOL
 
@@ -53,8 +50,6 @@
 #include "common/memorypool.h"
 #endif
 
-
-
 namespace Common {
 
 /**
@@ -76,15 +71,15 @@ template<class T> class IteratorImpl;
 
 /**
  * HashMap<Key,Val> maps objects of type Key to objects of type Val.
- * For each used Key type, we need an "size_type hashit(Key,size_type)" function
+ * For each used Key type, a "size_type hashit(Key,size_type)" function
- * that computes a hash for the given Key object and returns it as an
+ * is required that computes a hash for the given Key object and returns it as
- * an integer from 0 to hashsize-1, and also an "equality functor".
+ * an integer from 0 to hashsize-1. An "equality functor" is also required
- * that returns true if if its two arguments are to be considered
+ * that returns true if its two arguments are to be considered
- * equal. Also, we assume that "=" works on Val objects for assignment.
+ * equal. Also, it is assumed that "=" works on Val objects for assignment.
  *
- * If aa is an HashMap<Key,Val>, then space is allocated each time aa[key] is
+ * If aa is a HashMap<Key,Val>, then space is allocated each time aa[key] is
  * referenced, for a new key. If the object is const, then an assertion is
- * triggered instead. Hence if you are not sure whether a key is contained in
+ * triggered instead. Hence, if you are not sure whether a key is contained in
  * the map, use contains() first to check for its presence.
  */
 template<class Key, class Val, class HashFunc = Hash<Key>, class EqualFunc = EqualTo<Key> >
@@ -301,7 +296,7 @@ public:
 	}
 
 	// TODO: insert() method?
-
+    /** Return true if hashmap is empty. */
 	bool empty() const {
 		return (_size == 0);
 	}
@@ -332,8 +327,8 @@ HashMap<Key, Val, HashFunc, EqualFunc>::HashMap() : _defaultVal() {
 
 /**
  * Copy constructor, creates a full copy of the given hashmap.
- * We must provide a custom copy constructor as we use pointers
+ * A custom copy constructor must be provided as pointers
- * to heap buffers for the internal storage.
+ * to heap buffers are used for the internal storage.
  */
 template<class Key, class Val, class HashFunc, class EqualFunc>
 HashMap<Key, Val, HashFunc, EqualFunc>::HashMap(const HM_t &map) :
@@ -365,7 +360,7 @@ HashMap<Key, Val, HashFunc, EqualFunc>::~HashMap() {
  * Internal method for assigning the content of another HashMap
  * to this one.
  *
- * @note We do *not* deallocate the previous storage here -- the caller is
+ * @note The previous storage here is *not* deallocated here -- the caller is
  *       responsible for doing that!
  */
 template<class Key, class Val, class HashFunc, class EqualFunc>
@@ -393,6 +388,9 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::assign(const HM_t &map) {
 	assert(_deleted == map._deleted);
 }
 
+/**
+ * Clear all values in the hashmap.
+ */
 
 template<class Key, class Val, class HashFunc, class EqualFunc>
 void HashMap<Key, Val, HashFunc, EqualFunc>::clear(bool shrinkArray) {
@@ -555,6 +553,9 @@ typename HashMap<Key, Val, HashFunc, EqualFunc>::size_type HashMap<Key, Val, Has
 	return ctr;
 }
 
+/**
+ * Check whether the hashmap contains the given key.
+ */
 
 template<class Key, class Val, class HashFunc, class EqualFunc>
 bool HashMap<Key, Val, HashFunc, EqualFunc>::contains(const Key &key) const {
@@ -562,16 +563,28 @@ bool HashMap<Key, Val, HashFunc, EqualFunc>::contains(const Key &key) const {
 	return (_storage[ctr] != nullptr);
 }
 
+/**
+ * Get a value from the hashmap.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 Val &HashMap<Key, Val, HashFunc, EqualFunc>::operator[](const Key &key) {
 	return getVal(key);
 }
 
+/**
+ * @overload
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 const Val &HashMap<Key, Val, HashFunc, EqualFunc>::operator[](const Key &key) const {
 	return getVal(key);
 }
 
+/**
+ * Get a value from the hashmap.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) {
 	size_type ctr = lookupAndCreateIfMissing(key);
@@ -579,11 +592,19 @@ Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) {
 	return _storage[ctr]->_value;
 }
 
+/**
+ * @overload
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) const {
 	return getVal(key, _defaultVal);
 }
 
+/**
+ * Get a value from the hashmap. If the key is not present, then return @p defaultVal.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key, const Val &defaultVal) const {
 	size_type ctr = lookup(key);
@@ -593,6 +614,10 @@ const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key, const
 		return defaultVal;
 }
 
+/**
+ * Assign an element specified by @p key to a value @p val.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 bool HashMap<Key, Val, HashFunc, EqualFunc>::tryGetVal(const Key &key, Val &out) const {
 	size_type ctr = lookup(key);
@@ -611,6 +636,10 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::setVal(const Key &key, const Val &v
 	_storage[ctr]->_value = val;
 }
 
+/**
+ * Erase an element referred to by an iterator.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 void HashMap<Key, Val, HashFunc, EqualFunc>::erase(iterator entry) {
 	// Check whether we have a valid iterator
@@ -628,6 +657,10 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::erase(iterator entry) {
 	_deleted++;
 }
 
+/**
+ * Erase an element specified by a key.
+ */
+
 template<class Key, class Val, class HashFunc, class EqualFunc>
 void HashMap<Key, Val, HashFunc, EqualFunc>::erase(const Key &key) {
 

common/huffman.h

@@ -32,13 +32,13 @@
 namespace Common {
 
 /**
- * @defgroup common_huffmann Huffman bitstream decoding
+ * @defgroup common_huffmann Huffman bit stream decoding
  * @ingroup common
  *
- * @brief API for operations related to Huffman bitstream decoding.
+ * @brief API for operations related to Huffman bit stream decoding.
  * 
  * @details Used in engines:
- *          - scumm
+ *          - SCUMM
  *		
  * @{
  */
@@ -53,7 +53,7 @@ inline uint32 REVERSEBITS(uint32 x) {
 }
 
 /**
- * Huffman bitstream decoding
+ * Huffman bit stream decoding.
  *
  */
 template<class BITSTREAM>
@@ -61,15 +61,15 @@ class Huffman {
 public:
 	/** Construct a Huffman decoder.
 	 *
-	 *  @param maxLength Maximal code length. If 0, it's searched for.
+	 *  @param maxLength Maximal code length. If 0, it is searched for.
 	 *  @param codeCount Number of codes.
-	 *  @param codes The actual codes.
+	 *  @param codes     The actual codes.
-	 *  @param lengths Lengths of the individual codes.
+	 *  @param lengths   Lengths of the individual codes.
-	 *  @param symbols The symbols. If 0, assume they are identical to the code indices.
+	 *  @param symbols   The symbols. If 0, assume they are identical to the code indices.
 	 */
 	Huffman(uint8 maxLength, uint32 codeCount, const uint32 *codes, const uint8 *lengths, const uint32 *symbols = nullptr);
 
-	/** Return the next symbol in the bitstream. */
+	/** Return the next symbol in the bit stream. */
 	uint32 getSymbol(BITSTREAM &bits) const;
 
 private:
@@ -111,13 +111,13 @@ Huffman<BITSTREAM>::Huffman(uint8 maxLength, uint32 codeCount, const uint32 *cod
 
 	assert(maxLength <= 32);
 
-	// Codes that don't fit in the prefix table are stored in the _codes array
+	// Codes that do not fit in the prefix table are stored in the _codes array.
 	_codes.resize(MAX(maxLength - _prefixTableBits, 0));
 
 	for (uint i = 0; i < codeCount; i++) {
 		uint8 length = lengths[i];
 
-		// The symbol. If none were specified, just assume it's identical to the code index
+		// The symbol. If none was specified, assume it is identical to the code index.
 		uint32 symbol = symbols ? symbols[i] : i;
 
 		if (length <= _prefixTableBits) {
@@ -138,7 +138,7 @@ Huffman<BITSTREAM>::Huffman(uint8 maxLength, uint32 codeCount, const uint32 *cod
 				_prefixTable[index].length = length;
 			}
 		} else {
-			// Put the code and symbol into the correct list for the length
+			// Put the code and symbol into the correct list for the length.
 			_codes[lengths[i] - 1 - _prefixTableBits].push_back(Symbol(codes[i], symbol));
 		}
 	}

common/ini-file.h

@@ -43,48 +43,51 @@ class SeekableReadStream;
 class WriteStream;
 
 /**
- * This class allows reading/writing INI style config files.
+ * This class allows for reading and writing INI-style config files.
  *
  * Lines starting with a '#' are ignored (i.e. treated as comments).
  * Some effort is made to preserve comments, though.
  *
  * This class makes no attempts to provide fast access to key/value pairs.
- * In particular, it stores all sections and k/v pairs in lists, not
+ * In particular, it stores all sections and key/value pairs in lists, not
  * in dictionaries/maps. This makes it very easy to read/write the data
  * from/to files, but of course is not appropriate for fast access.
  * The main reason is that this class is indeed geared toward doing precisely
- * that!
+ * that.
  */
 class INIFile {
 public:
 	struct KeyValue {
-		String key;
+		String key;     /*!< Key of the configuration entry. */
-		String value;
+		String value;   /*!< Value of the configuration entry. */
-		String comment;
+		String comment; /*!< Comment within an INI file. */
 	};
 
-	typedef List<KeyValue> SectionKeyList;
+	typedef List<KeyValue> SectionKeyList; /*!< A list of all key/value pairs in this section. */
 
-	/** A section in a ini file. I.e. corresponds to something like this:
+	/** A section in an INI file.
-	 *   [mySection]
-	 *   key=value
 	 *
-	 * Comments are also stored, to keep users happy who like editing their
+	 * Corresponds to the following:
-	 * ini files manually.
+	 * @code
+	 * [mySection]
+	 * key=value
+	 * @endcode
+	 * Comments are also stored, for convenience of users who prefer to edit
+	 * INI files manually.
 	 */
 	struct Section {
-		String name;
+		String name;         /*!< Name of the section. */
-		List<KeyValue> keys;
+		List<KeyValue> keys; /*!< List of all keys in this section. */
-		String comment;
+		String comment;      /*!< Comment within the section. */
 
-		bool hasKey(const String &key) const;
+		bool hasKey(const String &key) const; /*!< Check whether the section has a @p key. */
-		const KeyValue* getKey(const String &key) const;
+		const KeyValue* getKey(const String &key) const; /*!< Get the value assigned to a @p key. */
-		void setKey(const String &key, const String &value);
+		void setKey(const String &key, const String &value); /*!< Assign a @p value to a @p key. */
-		void removeKey(const String &key);
+		void removeKey(const String &key); /*!< Remove a @p key from this section. */
-		const SectionKeyList getKeys() const { return keys; }
+		const SectionKeyList getKeys() const { return keys; } /*!< Get a list of all keys in the section. */
 	};
 
-	typedef List<Section> SectionList;
+	typedef List<Section> SectionList; /*!< A list of all sections in this INI file. */
 
 public:
 	INIFile();
@@ -94,40 +97,40 @@ public:
 
 	/**
 	 * Check whether the given string is a valid section or key name.
-	 * For that, it must only consist of letters, numbers, dashes and
+	 * For that, it must only consist of letters, numbers, dashes, and
-	 * underscores. In particular, white space and "#", "=", "[", "]"
+	 * underscores. In particular, whitespace and "#", "=", "[", "]"
-	 * are not valid!
+	 * are not valid.
 	 */
 	bool isValidName(const String &name) const;
 
-	/** Reset everything stored in this ini file. */
+	/** Reset everything stored in this INI file. */
 	void	clear();
 
-	bool	loadFromFile(const String &filename);
+	bool	loadFromFile(const String &filename); /*!< Load configuration from a file. */
-	bool	loadFromSaveFile(const String &filename);
+	bool	loadFromSaveFile(const String &filename); /*!< Load configuration from a save file. */
-	bool	loadFromStream(SeekableReadStream &stream);
+	bool	loadFromStream(SeekableReadStream &stream); /*!< Load configuration from a @ref SeekableReadStream. */
-	bool	saveToFile(const String &filename);
+	bool	saveToFile(const String &filename); /*!< Save the current configuration to a file. */
-	bool	saveToSaveFile(const String &filename);
+	bool	saveToSaveFile(const String &filename); /*!< Save the current configuration to a save file. */
-	bool	saveToStream(WriteStream &stream);
+	bool	saveToStream(WriteStream &stream); /*!< Save the current configuration to a @ref WriteStream. */
 
-	bool	hasSection(const String &section) const;
+	bool	hasSection(const String &section) const; /*!< Check whether the INI file has a section with the specified name. */
-	void	addSection(const String &section);
+	void	addSection(const String &section); /*!< Add a section with the specified name to the INI file. */
-	void	removeSection(const String &section);
+	void	removeSection(const String &section); /*!< Remove the @p section from the INI file. */
-	void	renameSection(const String &oldName, const String &newName);
+	void	renameSection(const String &oldName, const String &newName); /*!< Rename the INI file from @p oldName to @p newName. */
 
-	void	setDefaultSectionName(const String &name); ///< sets initial section name for section-less ini files
+	void	setDefaultSectionName(const String &name); /*!< Set initial section name for section-less INI files. */
 
-	bool	hasKey(const String &key, const String &section) const;
+	bool	hasKey(const String &key, const String &section) const; /*!< Check whether the @p section has a @p key. */
-	bool	getKey(const String &key, const String &section, String &value) const;
+	bool	getKey(const String &key, const String &section, String &value) const; /*!< Get the @p value of a @p key in a @p section. */
-	void	setKey(const String &key, const String &section, const String &value);
+	void	setKey(const String &key, const String &section, const String &value); /*!< Assign a @p value to a @p key in a @p section. */
-	void	removeKey(const String &key, const String &section);
+	void	removeKey(const String &key, const String &section); /*!< Remove a @p key from this @p section. */
 
-	const SectionList getSections() const { return _sections; }
+	const SectionList getSections() const { return _sections; } /*!< Get a list of sections in this INI file. */
-	const SectionKeyList getKeys(const String &section) const;
+	const SectionKeyList getKeys(const String &section) const; /*!< Get a list of keys in a @p section. */
 
-	void listKeyValues(StringMap &kv);
+	void listKeyValues(StringMap &kv); /*!< Get a list of all key/value pairs in this INI file. */
 
-	void allowNonEnglishCharacters();
+	void allowNonEnglishCharacters(); /*!< Allow non-English characters in this INI file. */
 
 private:
 	String		_defaultSectionName;

doc/doxygen/scummvm.doxyfile

@@ -238,10 +238,7 @@ TAB_SIZE               = 4
 # "Side Effects:". You can put \n's in the value part of an alias to insert
 # newlines.
 
-ALIASES                = "tip_s=<span class=\"tip\">" \
+ALIASES                = 
-                         "tip_e=</span>" \
-                         "warn_s=<span class=\"warn\">" \
-                         "warn_e=</span>" \
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -626,7 +623,7 @@ STRICT_PROTO_MATCHING  = NO
 # list. This list is created by putting \todo commands in the documentation.
 # The default value is: YES.
 
-GENERATE_TODOLIST      = YES
+GENERATE_TODOLIST      = NO
 
 # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
 # list. This list is created by putting \test commands in the documentation.
@@ -2048,7 +2045,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2088,7 +2085,10 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = 
+PREDEFINED             = USE_SYSDIALOGS \ 
+                         SCUMM_NEED_ALIGNMENT \ 
+                         SCUMM_LITTLE_ENDIAN \
+                         SCUMM_BIG_ENDIAN \
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The