[Scummvm-git-logs] scummvm master -> 24e3b6096ee8e680c1b73445baf430934f30ebca
criezy
criezy at scummvm.org
Wed Nov 4 19:42:39 UTC 2020
This automated email contains information about 1 new commit which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .
Summary:
24e3b6096e DOXYGEN: Doxygen improvements part 3
Commit: 24e3b6096ee8e680c1b73445baf430934f30ebca
https://github.com/scummvm/scummvm/commit/24e3b6096ee8e680c1b73445baf430934f30ebca
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-11-04T19:42:34Z
Commit Message:
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.
Changed paths:
common/debug.h
common/dialogs.h
common/encoding.h
common/endian.h
common/error.h
common/events.h
common/fft.h
common/file.h
common/frac.h
common/fs.h
common/gui_options.h
common/hash-ptr.h
common/hashmap.h
common/huffman.h
common/ini-file.h
doc/doxygen/scummvm.doxyfile
diff --git a/common/debug.h b/common/debug.h
index eb70f958cf..a0f0d7f467 100644
--- a/common/debug.h
+++ b/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);
diff --git a/common/dialogs.h b/common/dialogs.h
index 083104d3b5..d1e5551e6f 100644
--- a/common/dialogs.h
+++ b/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
- kDialogCancel = 0, ///< User cancelled the dialog (Cancel/No/Close buttons)
- kDialogOk = 1 ///< User confirmed the dialog (OK/Yes buttons)
+ kDialogError = -1, ///< Dialog could not be displayed.
+ kDialogCancel = 0, ///< User cancelled the dialog (Cancel/No/Close 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 choice The path selected by the user
- * @param isDirBrowser Restrict selection to directories
- * @return The dialog result
+ * @param title Dialog title.
+ * @param choice Path selected by the user.
+ * @param isDirBrowser Restrict selection to directories.
+ * @return The dialog result.
*/
virtual DialogResult showFileBrowser(const Common::U32String &title, FSNode &choice, bool isDirBrowser = false) { return kDialogError; }
diff --git a/common/encoding.h b/common/encoding.h
index 6d91bb3a46..054da9b9a2 100644
--- a/common/encoding.h
+++ b/common/encoding.h
@@ -40,47 +40,48 @@ namespace Common {
*/
/**
- * A class, that allows conversion between different text encoding,
- * the encodings available depend on the current backend and if the
+ * A class that allows conversion between different text encoding.
+ * 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 from Name of the encoding the strings will be converted from
+ * @param to Name of the encoding the strings will be converted to.
+ * @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
- * 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)
+ * Convert a string between encodings.
*
- * 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.
- * 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)
+ * Convert a string between encodings.
*
- * 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 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 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 length Length of the string in bytes
+ * @param string Array containing the characters of a string.
+ * @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.
- * The string must be zero ended. Similar to strlen
- * (could be used instead of strlen).
+ * Compute the length (in bytes) of a string in a given encoding.
+ *
+ * The string must be zero ended. Similar to @c strlen.
*
- * @param string String, which size should be computed.
+ * @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 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 *convertWithTransliteration(const String &to, const String &from, const char *string, size_t length);
/**
- * Calls as many conversion functions as possible or until the conversion
- * succeeds. It first tries to use iconv, then it tries to use platform
- * specific functions and after that it tries to use TransMan mapping.
+ * Call as many conversion functions as possible, or until the conversion
+ * succeeds.
*
- * 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
- * @param from Name of the encoding the strings will be converted from
- * @param string String that should be converted.
+ * The result must be freed after usage.
+ *
+ * @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 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 *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
- * to the final encoding. Important encodings, that aren't supported by
+ * Use a conversion table to convert the string to unicode, and from that,
+ * 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 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 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
- * it's ASCII (latin) form.
+ * Transliterate a Cyrillic string in ISO-8859-5 encoding and return
+ * 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 length Length of the string in bytes
+ * @param string The string to convert.
+ * @param length Length of the string in bytes.
*
* @return Transliterated string in UTF-32 (must be freed) or nullptr on fail.
*/
diff --git a/common/endian.h b/common/endian.h
index 6ba2709b5e..dfddd2d0d8 100644
--- a/common/endian.h
+++ b/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_CONSTANT_??(a) - inverse byte order, implemented as macro.
- * Use with compiletime-constants only, the result will be a compiletime-constant aswell.
- * Unlike most other functions these can be used for eg. switch-case labels
- *
- * READ_UINT??(a) - read native value from pointer a
- * READ_??_UINT??(a) - read LE/BE value from pointer a and convert it to native
- * WRITE_??_UINT??(a, v) - write native value v to pointer a with LE/BE encoding
- * TO_??_??(a) - convert native value v to LE/BE
- * FROM_??_??(a) - convert LE/BE value v to native
- * CONSTANT_??_??(a) - convert LE/BE value v to native, implemented as macro.
- * Use with compiletime-constants only, the result will be a compiletime-constant aswell.
- * Unlike most other functions these can be used for eg. switch-case labels
+ * - SWAP_BYTES_??(a) - Reverse byte order
+ * - SWAP_CONSTANT_??(a) - Reverse byte order, implemented as a macro.
+ * 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 e.g. switch-case labels.
+ * - READ_UINT??(a) - Read native value from pointer @p a.
+ * - READ_??_UINT??(a) - Read LE/BE value from pointer @p a and convert it to native.
+ * - WRITE_??_UINT??(a, v) - Write a native value @p v to pointer @p a with LE/BE encoding.
+ * - TO_??_??(a) - Convert native value @p v to LE/BE.
+ * - FROM_??_??(a) - Convert LE/BE value @p v to native.
+ * - CONSTANT_??_??(a) - Convert LE/BE value @p v to native, implemented as a macro.
+ * 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 e.g. 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
- * be used for character constants. Hence if one uses multi-byte character
+ * 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
* 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.
-// They also transparently handle the need for alignment.
+/** @name Functions for reading and writing native integers
+ * @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
diff --git a/common/error.h b/common/error.h
index 4962c84ef7..810eb724e7 100644
--- a/common/error.h
+++ b/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
- kNoGameDataFoundError, ///< Engine initialization: No game data was found in the specified location
- kUnsupportedGameidError, ///< Engine initialization: Gameid not supported by this (Meta)Engine
- kUnsupportedColorMode, ///< Engine initialization: Engine does not support backend's color mode
- kAudioDeviceInitFailed, ///< Engine initialization: Audio device initialization failed
-
- kReadPermissionDenied, ///< Unable to read data due to missing read permission
- kWritePermissionDenied, ///< Unable to write data due to missing write permission
+ kNoError = 0, ///< No error occurred.
+ kNoGameDataFoundError, ///< Engine initialization: No game data was found in the specified location.
+ kUnsupportedGameidError, ///< Engine initialization: Game ID not supported by this (Meta)Engine.
+ kUnsupportedColorMode, ///< Engine initialization: Engine does not support backend's color mode.
+ kAudioDeviceInitFailed, ///< Engine initialization: Audio device initialization failed.
- kPathDoesNotExist, ///< The specified path does not exist
- kPathNotDirectory, ///< The specified path does not point to a directory
- kPathNotFile, ///< The specified path does not point to a file
+ kReadPermissionDenied, ///< Unable to read data due to missing read permission.
+ kWritePermissionDenied, ///< Unable to write data due to missing write permission.
- kCreatingFileFailed, ///< Failed creating a (savestate) file
- kReadingFailed, ///< Failed to read a file (permission denied?)
- kWritingFailed, ///< Failure to write data -- disk full?
+ kPathDoesNotExist, ///< The specified path does not exist.
+ kPathNotDirectory, ///< The specified path does not point to a directory.
+ kPathNotFile, ///< The specified path does not point to a file.
- // The following are used by --list-saves
+ kCreatingFileFailed, ///< Failed creating a (savestate) file.
+ kReadingFailed, ///< Failed to read a file (permission denied?).
+ kWritingFailed, ///< Failure to write data - disk full?
- // 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, ///< See comment above
+ /** 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,
- kEnginePluginNotFound, ///< Failed to find a Engine plugin to handle target
- kEnginePluginNotSupportSaves, ///< Failed if plugin does not support listing save states
+ kEnginePluginNotFound, ///< Failed to find an Engine plugin to handle target.
+ kEnginePluginNotSupportSaves, ///< The plugin does not support listing save states.
- kUserCanceled, ///< User has canceled the launching of the game
+ 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;
- String _desc;
+ ErrorCode _code; /*!< Error code. */
+ String _desc; /*!< Error description. */
public:
/**
* Construct a new Error with the specified error code and the default
diff --git a/common/events.h b/common/events.h
index fd10b8dc22..84594e880b 100644
--- a/common/events.h
+++ b/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.
- * TODO: Fingolfin suggests that it would be of better value to expand
+ * The backend requests the AGI engine's predictive dialog to be shown.
+ *
+ * @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
- * and or user.
+ * An example for this is OSystem, which provides events created by the system
+ * 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.
- * @return true if an event was polled, false otherwise.
+ * @param event Reference to the event struct where the event should be stored.
+ * @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
- * made up by client specific events.
+ * An artificial event source. This class is used as an event source, which is
+ * 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.
- * @return true if the event should not be passed to other observers,
+ * @param event The event that is incoming.
+ * @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
- * with higher priority will be notified before observers with
- * lower priority. Because of the possibility that oberservers
- * might 'eat' events, not all observers might be notified.
+ * EventDispatcher uses a priority-based approach. Observers
+ * with higher priority are notified before observers with
+ * lower priority. Note that observers might 'eat' events,
+ * 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
- * currently it is used by keyMapper
+ * @param listenPolls If set, then all pollEvent() calls are passed to the observer.
+ * 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.
- * @return true if an event was retrieved.
+ * @param event Point to an Event struct, which will be filled with the event data.
+ * @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
- * received an EVENT_QUIT.
+ * Whether the application should terminate. Set to true if EVENT_QUIT was received.
*/
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
- * *all* events, we might to change that in the future though.
+ * Priority of the event manager. For now, it is lowest since it eats
+ * *all* events. This might be changed in the future though.
*/
kEventManPriority = 0,
/**
- * Priority of the event recorder. It has to go after event manager
- * in order to record events generated by it
+ * Priority of the event recorder. It must go after the event manager
+ * 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.
diff --git a/common/fft.h b/common/fft.h
index 2a9f216650..88ca693002 100644
--- a/common/fft.h
+++ b/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.
diff --git a/common/file.h b/common/file.h
index e06f75d5ca..42240e240b 100644
--- a/common/file.h
+++ b/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
- * @return true if the file exists, false otherwise
+ * @param filename The file to check for.
+ * @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.
- * @note Must not be called if this file already is open (i.e. if isOpen returns true).
+ * Try to open the file with the given file name, by searching SearchMan.
+ * @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
- * @return true if file was opened successfully, false otherwise
+ * @param filename Name of the file to open.
+ * @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.
- * @note Must not be called if this file already is open (i.e. if isOpen returns true).
+ * Try to open the file with the given file name from within the given archive.
+ * @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 archive the archive in which to search for the file
- * @return true if file was opened successfully, false otherwise
+ * @param filename Name of the file to open.
+ * @param archive Archive in which to search for the file.
+ * @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.
- * @return true if file was opened successfully, false otherwise
+ * @param node The node to consider.
+ * @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
- * is a NULL pointer, we gracefully treat this as if opening failed.
+ * Try to 'open' the given stream. That is, wrap around it, and if the stream
+ * 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 name a string describing the 'file' corresponding to stream
- * @return true if stream was non-zero, false otherwise
+ * @param stream Pointer to a SeekableReadStream, or 0.
+ * @param name String describing the 'file' corresponding to the stream.
+ * @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
- void clearErr() override; // implement abstract Stream method
- bool eos() const override; // implement abstract SeekableReadStream method
+ bool err() const override; /*!< Implement abstract Stream method. */
+ void clearErr() override; /*!< Implement abstract Stream method. */
+ bool eos() const override; /*!< Implement abstract SeekableReadStream method. */
- int32 pos() 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
- uint32 read(void *dataPtr, uint32 dataSize) override; // implement abstract SeekableReadStream method
+ int32 pos() 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. */
+ 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;
diff --git a/common/frac.h b/common/frac.h
index c6637b3bde..7acbf51a1d 100644
--- a/common/frac.h
+++ b/common/frac.h
@@ -35,8 +35,8 @@
*/
/**
- * The precision of the fractional (fixed point) type we define below.
- * Normally you should never have to modify this value.
+ * The precision of the fractional (fixed-point) type that is defined below.
+ * Normally, you should never need to modify this value.
*/
enum {
FRAC_BITS = 16,
diff --git a/common/fs.h b/common/fs.h
index 43024499d3..1093a4bbdb 100644
--- a/common/fs.h
+++ b/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.
- * This is subclass instead of just a typedef so that we can use forward
- * declarations of it in other places.
+ * List of multiple file system nodes. For example, the contents of a given directory.
+ * This is a subclass instead of just a typedef so that forward declarations
+ * 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
- * @return the node referring to the child with the given name
+ * @param name Name of a child of this directory.
+ * @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
- * system anyway.
+ * the above criteria. What a 'path' is differs greatly from system to
+ * 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
- * node refers to non-existing directory. If this is not the case,
+ * Create a directory referred by this node. This assumes that this
+ * 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
- * specific comments for more information.
+ * hasFile(), listMatchingMembers(), and listMembers(). See the function-specific
+ * 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
- * c:\my\data\file.ext would be cached as file.ext.
+ * are cached without the relative path, so in the following example:
+ * @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
- * getSubDirectory shouldn't be used on clashing directories. This flag is useful
- * in flat mode when there are directories with same name at different places in the
- * tree whose name isn't relevant for the engine code.
+ * expected by the engine. It means that files that clash should be identical and
+ * getSubDirectory should not be used on clashing directories. This flag is useful
+ * in flat mode when there are directories with the same name at different places in the
+ * 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
- * and using 'your' as prefix, the cache entry would have been 'your/data/file.ext'.
+ * a trailing slash to the prefix if needed. Following on with the previous example
+ * 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
- * for an explanation of the prefix parameter.
- * @return a new FSDirectory instance
+ * Create a new FSDirectory pointing to a subdirectory of the 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
- * for success.
+ * Check for the existence of a file in the cache. A full match of relative path and file name
+ * 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
- * path and filename is needed for success.
+ * Get an ArchiveMember representation of the specified file. A full match of relative
+ * 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;
diff --git a/common/gui_options.h b/common/gui_options.h
index 4a10a8df89..fe35ff4bb6 100644
--- a/common/gui_options.h
+++ b/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
- * domain, when they differ to the ones passed as
+ * Update the GUI options of the current config manager
+ * domain when they differ to the ones passed as
* parameter.
*/
void updateGameGUIOptions(const String &options, const String &langOption);
diff --git a/common/hash-ptr.h b/common/hash-ptr.h
index d27cdf4118..348988dc61 100644
--- a/common/hash-ptr.h
+++ b/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 *> {
diff --git a/common/hashmap.h b/common/hashmap.h
index 2795ca1d01..31984dacfe 100644
--- a/common/hashmap.h
+++ b/common/hashmap.h
@@ -26,19 +26,16 @@
#ifndef COMMON_HASHMAP_H
#define COMMON_HASHMAP_H
-/**
- * @def DEBUG_HASH_COLLISIONS
- * Enable the following #define if you want to check how many collisions the
- * code produces (many collisions indicate either a bad hash function, or a
- * hash table that is too small).
- */
+// Enable the following #define if you want to check how many collisions the
+// 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
- speed quite a bit.
+ * nodes they contain. This increases memory usage, but can also improve
+ * 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
- * that computes a hash for the given Key object and returns it as an
- * an integer from 0 to hashsize-1, and also an "equality functor".
- * that returns true if if its two arguments are to be considered
- * equal. Also, we assume that "=" works on Val objects for assignment.
+ * For each used Key type, a "size_type hashit(Key,size_type)" function
+ * is required that computes a hash for the given Key object and returns it as
+ * an integer from 0 to hashsize-1. An "equality functor" is also required
+ * that returns true if its two arguments are to be considered
+ * 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
- * to heap buffers for the internal storage.
+ * A custom copy constructor must be provided as pointers
+ * 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) {
diff --git a/common/huffman.h b/common/huffman.h
index d98d90cc73..5462807115 100644
--- a/common/huffman.h
+++ b/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 lengths Lengths of the individual codes.
- * @param symbols The symbols. If 0, assume they are identical to the code indices.
+ * @param codes The actual codes.
+ * @param lengths Lengths of the individual codes.
+ * @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));
}
}
diff --git a/common/ini-file.h b/common/ini-file.h
index 4b66936ac0..74665fb0fd 100644
--- a/common/ini-file.h
+++ b/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 value;
- String comment;
+ String key; /*!< Key of the configuration entry. */
+ String value; /*!< Value of the configuration entry. */
+ 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:
- * [mySection]
- * key=value
+ /** A section in an INI file.
*
- * Comments are also stored, to keep users happy who like editing their
- * ini files manually.
+ * Corresponds to the following:
+ * @code
+ * [mySection]
+ * key=value
+ * @endcode
+ * Comments are also stored, for convenience of users who prefer to edit
+ * INI files manually.
*/
struct Section {
- String name;
- List<KeyValue> keys;
- String comment;
-
- bool hasKey(const String &key) const;
- const KeyValue* getKey(const String &key) const;
- void setKey(const String &key, const String &value);
- void removeKey(const String &key);
- const SectionKeyList getKeys() const { return keys; }
+ String name; /*!< Name of the section. */
+ List<KeyValue> keys; /*!< List of all keys in this section. */
+ String comment; /*!< Comment within the section. */
+
+ bool hasKey(const String &key) const; /*!< Check whether the section has a @p key. */
+ const KeyValue* getKey(const String &key) const; /*!< Get the value assigned to a @p key. */
+ void setKey(const String &key, const String &value); /*!< Assign a @p value to a @p key. */
+ void removeKey(const String &key); /*!< Remove a @p key from this section. */
+ 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
- * underscores. In particular, white space and "#", "=", "[", "]"
- * are not valid!
+ * For that, it must only consist of letters, numbers, dashes, and
+ * underscores. In particular, whitespace and "#", "=", "[", "]"
+ * 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 loadFromSaveFile(const String &filename);
- bool loadFromStream(SeekableReadStream &stream);
- bool saveToFile(const String &filename);
- bool saveToSaveFile(const String &filename);
- bool saveToStream(WriteStream &stream);
+ bool loadFromFile(const String &filename); /*!< Load configuration from a file. */
+ bool loadFromSaveFile(const String &filename); /*!< Load configuration from a save file. */
+ bool loadFromStream(SeekableReadStream &stream); /*!< Load configuration from a @ref SeekableReadStream. */
+ bool saveToFile(const String &filename); /*!< Save the current configuration to a file. */
+ bool saveToSaveFile(const String &filename); /*!< Save the current configuration to a save file. */
+ bool saveToStream(WriteStream &stream); /*!< Save the current configuration to a @ref WriteStream. */
- bool hasSection(const String §ion) const;
- void addSection(const String §ion);
- void removeSection(const String §ion);
- void renameSection(const String &oldName, const String &newName);
+ bool hasSection(const String §ion) const; /*!< Check whether the INI file has a section with the specified name. */
+ void addSection(const String §ion); /*!< Add a section with the specified name to the INI file. */
+ void removeSection(const String §ion); /*!< Remove the @p section from the INI file. */
+ 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 §ion) const;
- bool getKey(const String &key, const String §ion, String &value) const;
- void setKey(const String &key, const String §ion, const String &value);
- void removeKey(const String &key, const String §ion);
+ bool hasKey(const String &key, const String §ion) const; /*!< Check whether the @p section has a @p key. */
+ bool getKey(const String &key, const String §ion, String &value) const; /*!< Get the @p value of a @p key in a @p section. */
+ void setKey(const String &key, const String §ion, const String &value); /*!< Assign a @p value to a @p key in a @p section. */
+ void removeKey(const String &key, const String §ion); /*!< Remove a @p key from this @p section. */
- const SectionList getSections() const { return _sections; }
- const SectionKeyList getKeys(const String §ion) const;
+ const SectionList getSections() const { return _sections; } /*!< Get a list of sections in this INI file. */
+ const SectionKeyList getKeys(const String §ion) 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;
diff --git a/doc/doxygen/scummvm.doxyfile b/doc/doxygen/scummvm.doxyfile
index 171b44f72b..6d2b6fffd7 100644
--- a/doc/doxygen/scummvm.doxyfile
+++ b/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\">" \
- "tip_e=</span>" \
- "warn_s=<span class=\"warn\">" \
- "warn_e=</span>" \
+ALIASES =
# 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
More information about the Scummvm-git-logs
mailing list