diff --git a/common/debug.h b/common/debug.h index eb70f958cf1..a0f0d7f4674 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 083104d3b59..d1e5551e6f8 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 6d91bb3a462..054da9b9a24 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. * - * @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 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 6ba2709b5eb..dfddd2d0d89 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(value)); } - +/** @} */ /** @} */ #endif diff --git a/common/error.h b/common/error.h index 4962c84ef76..810eb724e79 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 + 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. - kReadPermissionDenied, ///< Unable to read data due to missing read permission - kWritePermissionDenied, ///< Unable to write data due to missing write permission + kReadPermissionDenied, ///< Unable to read data due to missing read permission. + kWritePermissionDenied, ///< Unable to write data due to missing write permission. - 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 + 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. - kCreatingFileFailed, ///< Failed creating a (savestate) file - kReadingFailed, ///< Failed to read a file (permission denied?) - kWritingFailed, ///< Failure to write data -- disk full? + kCreatingFileFailed, ///< Failed creating a (savestate) file. + kReadingFailed, ///< Failed to read a file (permission denied?). + 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 - // be built into the executable, regardless if the engine plugins are present or not. - kMetaEnginePluginNotFound, ///< See comment above + kEnginePluginNotFound, ///< Failed to find an Engine plugin to handle target. + kEnginePluginNotSupportSaves, ///< The plugin does not support listing save states. - kEnginePluginNotFound, ///< Failed to find a Engine plugin to handle target - kEnginePluginNotSupportSaves, ///< Failed if 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 fd10b8dc228..84594e880b2 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 _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 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 2a9f2166505..88ca693002e 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 e06f75d5ca2..42240e240b9 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 c6637b3bded..7acbf51a1dc 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 43024499d39..1093a4bbdb2 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, 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 _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 4a10a8df891..fe35ff4bb68 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 d27cdf41187..348988dc61f 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 struct Hash { diff --git a/common/hashmap.h b/common/hashmap.h index 2795ca1d010..31984dacfee 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 IteratorImpl; /** * HashMap 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, then space is allocated each time aa[key] is + * If aa is a HashMap, 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 EqualFunc = EqualTo > @@ -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::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 HashMap::HashMap(const HM_t &map) : @@ -365,7 +360,7 @@ HashMap::~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 @@ -393,6 +388,9 @@ void HashMap::assign(const HM_t &map) { assert(_deleted == map._deleted); } +/** + * Clear all values in the hashmap. + */ template void HashMap::clear(bool shrinkArray) { @@ -555,6 +553,9 @@ typename HashMap::size_type HashMap bool HashMap::contains(const Key &key) const { @@ -562,16 +563,28 @@ bool HashMap::contains(const Key &key) const { return (_storage[ctr] != nullptr); } +/** + * Get a value from the hashmap. + */ + template Val &HashMap::operator[](const Key &key) { return getVal(key); } +/** + * @overload + */ + template const Val &HashMap::operator[](const Key &key) const { return getVal(key); } +/** + * Get a value from the hashmap. + */ + template Val &HashMap::getVal(const Key &key) { size_type ctr = lookupAndCreateIfMissing(key); @@ -579,11 +592,19 @@ Val &HashMap::getVal(const Key &key) { return _storage[ctr]->_value; } +/** + * @overload + */ + template const Val &HashMap::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 const Val &HashMap::getVal(const Key &key, const Val &defaultVal) const { size_type ctr = lookup(key); @@ -593,6 +614,10 @@ const Val &HashMap::getVal(const Key &key, const return defaultVal; } +/** + * Assign an element specified by @p key to a value @p val. + */ + template bool HashMap::tryGetVal(const Key &key, Val &out) const { size_type ctr = lookup(key); @@ -611,6 +636,10 @@ void HashMap::setVal(const Key &key, const Val &v _storage[ctr]->_value = val; } +/** + * Erase an element referred to by an iterator. + */ + template void HashMap::erase(iterator entry) { // Check whether we have a valid iterator @@ -628,6 +657,10 @@ void HashMap::erase(iterator entry) { _deleted++; } +/** + * Erase an element specified by a key. + */ + template void HashMap::erase(const Key &key) { diff --git a/common/huffman.h b/common/huffman.h index d98d90cc73f..5462807115e 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 @@ -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::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::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 4b66936ac07..74665fb0fd5 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 SectionKeyList; + typedef List 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 keys; - String comment; + String name; /*!< Name of the section. */ + List keys; /*!< List of all keys in this section. */ + String comment; /*!< Comment within the section. */ - 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; } + 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
SectionList; + typedef List
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 171b44f72b3..6d2b6fffd78 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=" \ - "tip_e=" \ - "warn_s=" \ - "warn_e=" \ +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