[Scummvm-git-logs] scummvm master -> fe9c51892cb0e01f1cb9152703b1e837c06755a0
criezy
criezy at scummvm.org
Sun Nov 22 16:57: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:
fe9c51892c DOXYGEN: doxygen review on remaining common headers
Commit: fe9c51892cb0e01f1cb9152703b1e837c06755a0
https://github.com/scummvm/scummvm/commit/fe9c51892cb0e01f1cb9152703b1e837c06755a0
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-11-22T16:57:25Z
Commit Message:
DOXYGEN: doxygen review on remaining common headers
- textconsole.h
- timer.h
- translation.h
- ustr.h
- util.h
Changed paths:
common/textconsole.h
common/timer.h
common/translation.h
common/ustr.h
common/util.h
diff --git a/common/textconsole.h b/common/textconsole.h
index 6a6baa45ed..f99909677d 100644
--- a/common/textconsole.h
+++ b/common/textconsole.h
@@ -39,6 +39,7 @@ namespace Common {
/**
* An output formatter takes a source string and 'decorates' it with
* extra information, storing the result in a destination buffer.
+ *
* A typical use is to (optionally) enhance the output given by
* the error() and debug() functions with extra information on
* the state of the active engine.
@@ -52,8 +53,9 @@ void setErrorOutputFormatter(OutputFormatter f);
/**
- * A callback which is invoked by error() just before aborting.
- * A typical example would be a function which shows a debug
+ * A callback that is invoked by error() just before aborting.
+ *
+ * A typical example would be a function that shows a debug
* console and displays the given message in it.
*/
typedef void (*ErrorHandler)(const char *msg);
@@ -62,6 +64,7 @@ typedef void (*ErrorHandler)(const char *msg);
* Set a callback that is invoked by error() after the error
* message has been printed, but before the application is
* terminated.
+ *
* This can be used to e.g. show a debugger console.
*/
void setErrorHandler(ErrorHandler handler);
@@ -70,7 +73,14 @@ void setErrorHandler(ErrorHandler handler);
} // End of namespace Common
+/**
+ * @addtogroup common_text_console
+ * @{
+ */
+/**
+ * Print an error message to the text console and then terminate the process.
+ */
void NORETURN_PRE error(const char *s, ...) GCC_PRINTF(1, 2) NORETURN_POST;
#ifdef DISABLE_TEXT_CONSOLE
@@ -81,12 +91,13 @@ inline void warning(const char *s, ...) {}
/**
* Print a warning message to the text console (stderr).
+ *
* Automatically prepends the text "WARNING: " and appends
* an exclamation mark and a newline.
*/
void warning(const char *s, ...) GCC_PRINTF(1, 2);
#endif
-
+/** @} */
#endif
diff --git a/common/timer.h b/common/timer.h
index d166289620..ec6f96ef77 100644
--- a/common/timer.h
+++ b/common/timer.h
@@ -40,28 +40,34 @@ namespace Common {
class TimerManager : NonCopyable {
public:
- typedef void (*TimerProc)(void *refCon);
+ typedef void (*TimerProc)(void *refCon); /*!< Type definition of a timer instance. */
virtual ~TimerManager() {}
/**
- * Install a new timer callback. It will from now be called every interval microseconds.
- * The timer may be invoked from a separate thread. Hence any timer code should be
+ * Install a new timer callback.
+ *
+ * After it has been created, the timer is called every @p interval microseconds.
+ * The timer can be invoked from a separate thread. Hence any timer code should be
* written following the same safety guidelines as any other threaded code.
*
* @note Although the interval is specified in microseconds, the actual timer resolution
- * may be lower. In particular, with the SDL backend the timer resolution is 10ms.
- * @param proc the callback
- * @param interval the interval in which the timer shall be invoked (in microseconds)
- * @param refCon an arbitrary void pointer; will be passed to the timer callback
- * @param id unique string id of the installed timer. Used by the event recorder
- * @return true if the timer was installed successfully, false otherwise
+ * may be lower. In particular, with the SDL backend the timer resolution is 10 ms.
+ *
+ * @param proc Callback.
+ * @param interval Interval in which the timer shall be invoked (in microseconds).
+ * @param refCon Arbitrary void pointer passed to the timer callback.
+ * @param id Unique string ID of the installed timer. Used by the event recorder.
+ *
+ * @return True if the timer was installed successfully, false otherwise.
*/
virtual bool installTimerProc(TimerProc proc, int32 interval, void *refCon, const Common::String &id) = 0;
/**
- * Remove the given timer callback. It will not be invoked anymore,
- * and no instance of this callback will be running anymore.
+ * Remove the given timer callback.
+ *
+ * It will not be invoked anymore, and no instance
+ * of this callback will be running anymore.
*/
virtual void removeTimerProc(TimerProc proc) = 0;
};
diff --git a/common/translation.h b/common/translation.h
index fdac736369..5cd8f6b16b 100644
--- a/common/translation.h
+++ b/common/translation.h
@@ -45,16 +45,26 @@ namespace Common {
class File;
+/**
+ * Translation IDs.
+ */
enum TranslationIDs {
- kTranslationAutodetectId = 0,
- kTranslationBuiltinId = 1000
+ kTranslationAutodetectId = 0, /*!< ID for the default language (the current system language). */
+ kTranslationBuiltinId = 1000 /*!< ID for the English language. */
};
+/**
+ * Structure describing a translation language.
+ */
struct TLanguage {
- U32String name;
- int id;
+ U32String name; /*!< Language name string. */
+ int id; /*!< Language ID. */
TLanguage() : id(0) {}
+
+ /**
+ * Construct a new language with name @p n and ID @p i.
+ */
TLanguage(const U32String &n, int i) : name(n), id(i) {}
};
@@ -62,10 +72,14 @@ bool operator<(const TLanguage &l, const TLanguage &r);
typedef Array<TLanguage> TLangArray;
+/**
+ * Structure describing a translated message.
+ */
struct PoMessageEntry {
- int msgid;
- String msgctxt;
- U32String msgstr;
+ int msgid; /*!< ID of the message. */
+ String msgctxt; /*!< Context of the message. It can be empty.
+ Can be used to solve ambiguities. */
+ U32String msgstr; /*!< Message string. */
};
/**
@@ -74,133 +88,145 @@ struct PoMessageEntry {
class TranslationManager : public Singleton<TranslationManager> {
public:
/**
- * The constructor detects the system language and sets default
- * language to English.
+ * Constructor that sets the current language to the default language.
+ *
+ * The default language is the detected system language.
*/
TranslationManager();
~TranslationManager();
/**
- * Retrieves the language string to the given id.
+ * Retrieve the language string from the given ID.
*
- * @param id Id of the language
- * @return the matching string description of the language
+ * @param id ID of the language.
+ *
+ * @return Matching string description of the language.
*/
String getLangById(int id) const;
/**
- * Sets the current translation language to the one specified in the
- * parameter. If the parameter is an empty string, it sets the default
- * system language.
+ * Set the current translation language to the one specified in the
+ * parameter.
+ *
+ * If the parameter is an empty string, it sets the translation language
+ * to the default system language.
*
- * @param lang Language to setup.
+ * @param lang Language to set up.
*/
void setLanguage(const String &lang);
/**
- * Sets the current translation language to the one specified by the
- * id parameter.
+ * Set the current translation language to the one specified by the
+ * @p id parameter.
*
- * @param id The id of the language.
+ * @param id ID of the language.
*/
void setLanguage(int id) {
setLanguage(getLangById(id));
}
/**
- * Parses a language string and returns an id instead.
+ * Get the ID for the given language string.
+ *
+ * @param lang Language string.
*
- * @param lang Language string
- * @return id of the language or kTranslationBuiltinId in case the
+ * @return ID of the language or kTranslationBuiltinId in case the
* language could not be found.
*/
int parseLanguage(const String &lang) const;
/**
- * Returns the translation into the current language of the parameter
- * message. In case the message isn't found in the translation catalog,
- * it returns the original untranslated message, as a U32String.
+ * Return the translation of @p message into the current language.
+ *
+ * In case the message is not found in the translation catalog,
+ * return the original untranslated message, as a U32String.
*/
U32String getTranslation(const char *message) const;
/**
- * Returns the translation into the current language of the parameter
- * message. In case the message isn't found in the translation catalog,
- * it returns the original untranslated message, as a U32String.
+ * Return the translation of @p message into the current language.
+ *
+ * In case the message is not found in the translation catalog,
+ * return the original untranslated message, as a U32String.
*/
U32String getTranslation(const String &message) const;
/**
- * Returns the translation into the current language of the parameter
- * message. In case the message isn't found in the translation catalog,
- * it returns the original untranslated message, as a U32String.
+ * Return the translation of @p message into the current language.
*
- * If a translation is found for the given context it will return that
- * translation, otherwise it will look for a translation for the same
- * massage without a context or with a different context.
+ * In case the message is not found in the translation catalog,
+ * return the original untranslated message, as a U32String.
+ *
+ * If a translation is found for the given context, return that
+ * translation. Otherwise, look for a translation for the same
+ * message without a context or with a different context.
*/
U32String getTranslation(const char *message, const char *context) const;
/**
- * Returns the translation into the current language of the parameter
- * message. In case the message isn't found in the translation catalog,
- * it returns the original untranslated message, as a U32String.
+ * Return the translation of @p message into the current language.
+ *
+ * In case the message is not found in the translation catalog,
+ * return the original untranslated message, as a U32String.
*
- * If a translation is found for the given context it will return that
- * translation, otherwise it will look for a translation for the same
- * massage without a context or with a different context.
+ * If a translation is found for the given context, return that
+ * translation. Otherwise, look for a translation for the same
+ * message without a context or with a different context.
*/
U32String getTranslation(const String &message, const String &context) const;
/**
- * Returns a list of supported languages.
+ * Return a list of supported languages.
*
- * @return The list of supported languages in a user readable form.
+ * @return The list of supported languages in a user-readable format.
*/
const TLangArray getSupportedLanguageNames() const;
/**
- * Returns charset specified by selected translation language
+ * Return the charset specified by the selected translation language.
*/
String getCurrentCharset() const;
/**
- * Returns currently selected translation language
+ * Return the currently selected translation language.
*/
String getCurrentLanguage() const;
private:
/**
- * Tries to find the given language or a derivate of it.
+ * Attempt to find the given language or a derivate of it.
+ *
+ * @param lang Language string.
*
- * @param lang Language string
- * @return id of the language or -1 in case no matching language could
+ * @return ID of the language or -1 in case no matching language could
* be found.
*/
int32 findMatchingLanguage(const String &lang);
/**
- * Find the translations.dat file. It looks first using the SearchMan and
- * then if needed using the Themepath. If found it opens the given File
- * to read the translations.dat file.
+ * Find the translations.dat file.
+ *
+ * First, search using the SearchMan and then, if needed, using the Themepath.
+ * If found, open the given @p File to read the translations.dat file.
*/
bool openTranslationsFile(File &);
/**
* Find the translations.dat file in the given directory node.
- * If found it opens the given File to read the translations.dat file.
+ *
+ * If found, open the given @p File to read the translations.dat file.
*/
bool openTranslationsFile(const FSNode &node, File &, int depth = -1);
/**
- * Load the list of languages from the translations.dat file
+ * Load the list of languages from the translations.dat file.
*/
void loadTranslationsInfoDat();
/**
- * Load the translation for the given language from the translations.dat file
+ * Load the translation for the given language from the translations.dat file.
*
- * @param index of the language in the list of languages
+ * @param index Index of the language in the list of languages.
*/
void loadLanguageDat(int index);
diff --git a/common/ustr.h b/common/ustr.h
index d40542e88f..84f9067124 100644
--- a/common/ustr.h
+++ b/common/ustr.h
@@ -31,7 +31,7 @@ namespace Common {
/**
* @defgroup common_ustr UTF-32 strings
- * @ingroup common_str
+ * @ingroup common
*
* @brief API for working with UTF-32 strings.
*
@@ -41,12 +41,12 @@ namespace Common {
class String;
/**
- * Very simple string class for UTF-32 strings in ScummVM. The main intention
+ * A simple string class for UTF-32 strings in ScummVM. The main intention
* behind this class is to feature a simple way of displaying UTF-32 strings
* through the Graphics::Font API.
*
- * Please note that operations like equals, deleteCharacter, toUppercase, etc.
- * are only very simplified convenience operations. They might not fully work
+ * Note that operations like equals, deleteCharacter, toUppercase, etc.
+ * are only simplified convenience operations. They might not fully work
* as you would expect for a proper UTF-32 string class.
*
* The presence of \0 characters in the string will cause undefined
@@ -60,15 +60,15 @@ typedef uint32 u32char_type_t;
class U32String : public BaseString<u32char_type_t> {
public:
- typedef uint32 unsigned_type;
+ typedef uint32 unsigned_type; /*!< Unsigned version of the underlying type. */
public:
/** Construct a new empty string. */
U32String() : BaseString<u32char_type_t>() {}
- /** Construct a new string from the given NULL-terminated C string. */
+ /** Construct a new string from the given null-terminated C string. */
explicit U32String(const value_type *str) : BaseString<u32char_type_t>(str) {}
- /** Construct a new string containing exactly len characters read from address str. */
+ /** Construct a new string containing exactly @p len characters read from address @p str. */
U32String(const value_type *str, uint32 len) : BaseString<u32char_type_t>(str, len) {}
#ifdef USE_CXX11
@@ -77,76 +77,110 @@ public:
U32String(const uint32 *beginP, const uint32 *endP) : BaseString<u32char_type_t>((const value_type *) beginP, (const value_type *) endP) {}
#endif
- /** Construct a new string containing the characters between beginP (including) and endP (excluding). */
+ /** Construct a new string containing the characters between @p beginP (including) and @p endP (excluding). */
U32String(const value_type *beginP, const value_type *endP) : BaseString<u32char_type_t>(beginP, endP) {}
/** Construct a copy of the given string. */
U32String(const U32String &str) : BaseString<u32char_type_t>(str) {}
- /** Construct a new string from the given NULL-terminated C string. */
+ /** Construct a new string from the given null-terminated C string that uses the given @p page encoding. */
explicit U32String(const char *str, CodePage page = kUtf8);
- /** Construct a new string containing exactly len characters read from address str. */
+ /** Construct a new string containing exactly @p len characters read from address @p str. */
U32String(const char *str, uint32 len, CodePage page = kUtf8);
- /** Construct a new string containing the characters between beginP (including) and endP (excluding). */
+ /** Construct a new string containing the characters between @p beginP (including) and @p endP (excluding). */
U32String(const char *beginP, const char *endP, CodePage page = kUtf8);
/** Construct a copy of the given string. */
U32String(const String &str, CodePage page = kUtf8);
+ /** Assign a given string to this string. */
U32String &operator=(const U32String &str);
+
+ /** @overload */
U32String &operator=(const String &str);
+
+ /** @overload */
U32String &operator=(const value_type *str);
+
+ /** @overload */
U32String &operator=(const char *str);
+
+ /** Append the given string to this string. */
U32String &operator+=(const U32String &str);
+
+ /** @overload */
U32String &operator+=(value_type c);
+
using BaseString<value_type>::operator==;
using BaseString<value_type>::operator!=;
+
+ /** Check whether this string is identical to string @p x. */
bool operator==(const String &x) const;
+
+ /** @overload */
bool operator==(const char *x) const;
+
+ /** Check whether this string is different than string @p x. */
bool operator!=(const String &x) const;
+
+ /** @overload */
bool operator!=(const char *x) const;
- /** Python-like method **/
+ /** Convert the string to the given @p page encoding and return the result as a new String. */
String encode(CodePage page = kUtf8) const;
/**
* Print formatted data into a U32String object.
+ *
+ * Similar to sprintf, except that it stores the result
+ * in a (variably sized) string instead of a fixed-size buffer.
*/
static U32String format(U32String fmt, ...);
+
+ /** @overload **/
static U32String format(const char *fmt, ...);
/**
- * Print formatted data into a U32String object. It takes in the
- * output by reference and works with iterators.
+ * Print formatted data into a U32String object.
+ * The method takes in the output by reference and works with iterators.
*/
static int vformat(const value_type *fmt, const value_type *fmtEnd, U32String &output, va_list args);
/**
- * Helper function for vformat, convert an int to string
- * minimal implementation, only for base 10
- */
+ * Helper function for vformat. Convert an int to string.
+ * Minimal implementation, only for base 10.
+ */
static char* itoa(int num, char* str, int base);
using BaseString<value_type>::insertString;
- void insertString(const char *s, uint32 p, CodePage page = kUtf8);
- void insertString(const String &s, uint32 p, CodePage page = kUtf8);
+ void insertString(const char *s, uint32 p, CodePage page = kUtf8); /*!< Insert string @p s into this string at position @p p. */
+ void insertString(const String &s, uint32 p, CodePage page = kUtf8); /*!< @overload */
/** Return a substring of this string */
U32String substr(size_t pos = 0, size_t len = npos) const;
- const uint32 *u32_str() const {
+ const uint32 *u32_str() const { /*!< Return the string as a UTF-32 pointer. */
return (const uint32 *) _str;
}
+ /** Decode a big endian UTF-16 string into a U32String. */
static Common::U32String decodeUTF16BE(const uint16 *start, uint len);
+
+ /** Decode a little endian UTF-16 string into a U32String. */
static Common::U32String decodeUTF16LE(const uint16 *start, uint len);
+
+ /** Decode a native UTF-16 string into a U32String. */
static Common::U32String decodeUTF16Native(const uint16 *start, uint len);
- /* Transform U32String into UTF-16 representation. The result must be freed. */
+ /** Transform a U32String into UTF-16 representation (big endian). The result must be freed. */
uint16 *encodeUTF16BE(uint *len = nullptr) const;
+
+ /** Transform a U32String into UTF-16 representation (native endian). The result must be freed. */
uint16 *encodeUTF16LE(uint *len = nullptr) const;
+
+ /** Transform a U32String into UTF-16 representation (native encoding). The result must be freed. */
uint16 *encodeUTF16Native(uint *len = nullptr) const;
private:
@@ -160,7 +194,10 @@ private:
friend class String;
};
+/** Concatenate strings @p x and @p y. */
U32String operator+(const U32String &x, const U32String &y);
+
+/** Append the given @p y character to the given @p x string. */
U32String operator+(const U32String &x, U32String::value_type y);
/** @} */
diff --git a/common/util.h b/common/util.h
index 273d027318..9b122cbb10 100644
--- a/common/util.h
+++ b/common/util.h
@@ -54,16 +54,23 @@
#undef MAX
#endif
+/** Template method to return the absolute value of @p x. */
template<typename T> inline T ABS(T x) { return (x >= 0) ? x : -x; }
+
+/** Template method to return the smallest of its parameters. */
template<typename T> inline T MIN(T a, T b) { return (a < b) ? a : b; }
+
+/** Template method to return the largest of its parameters. */
template<typename T> inline T MAX(T a, T b) { return (a > b) ? a : b; }
+
+/** Template method to clip the value @p v so that it remains between @p amin and @p amax. */
template<typename T> inline T CLIP(T v, T amin, T amax)
{
#if !defined(RELEASE_BUILD)
- // debug builds use this assert to pinpoint
+ // Debug builds use this assert to pinpoint
// any problematic cases, where amin and amax
// are incorrectly ordered
- // and thus CLIP() would return an invalid result
+ // and thus CLIP() would return an invalid result.
assert(amin <= amax);
#endif
if (v < amin) return amin;
@@ -72,7 +79,7 @@ template<typename T> inline T CLIP(T v, T amin, T amax)
}
/**
- * Template method which swaps the values of its two parameters.
+ * Template method to swap the values of its two parameters.
*/
template<typename T> inline void SWAP(T &a, T &b) { T tmp = a; a = b; b = tmp; }
@@ -81,7 +88,7 @@ template<typename T> inline void SWAP(T &a, T &b) { T tmp = a; a = b; b = tmp; }
#endif
/**
- * Macro which determines the number of entries in a fixed size array.
+ * Determine the number of entries in a fixed size array.
*/
#define ARRAYSIZE(x) ((int)(sizeof(x) / sizeof(x[0])))
@@ -90,8 +97,8 @@ template<typename T> inline void SWAP(T &a, T &b) { T tmp = a; a = b; b = tmp; }
*/
#define ARRAYEND(x) ((x) + ARRAYSIZE((x)))
-/*
- * Clear array using default or provided value
+/**
+ * Clear an array using the default or provided value.
*/
template<typename T, size_t N> inline void ARRAYCLEAR(T (&array) [N], const T &value = T()) {
T * ptr = array;
@@ -101,8 +108,7 @@ template<typename T, size_t N> inline void ARRAYCLEAR(T (&array) [N], const T &v
}
/**
- * @def SCUMMVM_CURRENT_FUNCTION
- * This macro evaluates to the current function's name on compilers supporting this.
+ * Evaluate the name of the current function on compilers supporting this.
*/
#if defined(__GNUC__)
# define SCUMMVM_CURRENT_FUNCTION __PRETTY_FUNCTION__
@@ -126,96 +132,116 @@ namespace Common {
/**
* Print a hexdump of the data passed in. The number of bytes per line is
* customizable.
- * @param data the data to be dumped
- * @param len the length of that data
- * @param bytesPerLine number of bytes to print per line (default: 16)
- * @param startOffset shift the shown offsets by the starting offset (default: 0)
+ *
+ * @param data The data to be dumped.
+ * @param len Length of that data.
+ * @param bytesPerLine Number of bytes to print per line (default: 16).
+ * @param startOffset Shift the shown offsets by the starting offset (default: 0).
*/
extern void hexdump(const byte * data, int len, int bytesPerLine = 16, int startOffset = 0);
/**
* Parse a string for a boolean value.
+ *
* The strings "true", "yes", and "1" are interpreted as true.
* The strings "false", "no", and "0" are interpreted as false.
* This function ignores case.
*
- * @param[in] val the string to parse
- * @param[out] valAsBool the parsing result
- * @return true if the string parsed correctly, false if an error occurred.
+ * @param[in] val The string to parse.
+ * @param[out] valAsBool Parsing result.
+ *
+ * @return True if the string has been parsed correctly, false if an error occurred.
*/
bool parseBool(const String &val, bool &valAsBool);
/**
* Test whether the given character is alphanumeric (a-z, A-Z, 0-9).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is alphanumeric, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is alphanumeric, false otherwise.
*/
bool isAlnum(int c);
/**
* Test whether the given character is an alphabetic letter (a-z, A-Z).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is alphabetic, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is alphabetic, false otherwise.
*/
bool isAlpha(int c);
/**
- * Test whether the given character is a decimal-digit (0-9).
+ * Test whether the given character is a decimal digit (0-9).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is a decimal-digit, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a decimal digit, false otherwise.
*/
bool isDigit(int c);
/**
- * Test whether the given character is a hwzadecimal-digit (0-9 or A-F).
+ * Test whether the given character is a hexadecimal digit (0-9 or A-F).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is a hexadecimal-digit, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a hexadecimal digit, false otherwise.
*/
bool isXDigit(int c);
/**
- * Test whether the given character is a lower-case letter (a-z).
+ * Test whether the given character is a lowercase letter (a-z).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is a lower-case letter, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a lowercase letter, false otherwise.
*/
bool isLower(int c);
/**
- * Test whether the given character is a white-space.
- * White-space characters are ' ', '\t', '\r', '\n', '\v', '\f'.
+ * Test whether the given character is a whitespace.
+ *
+ * The following characters are considered a whitespace:
+ * @code
+ * ' ', '\t', '\r', '\n', '\v', '\f'
+ * @endcode
*
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is a white-space, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a whitespace, false otherwise.
*/
bool isSpace(int c);
/**
- * Test whether the given character is an upper-case letter (A-Z).
+ * Test whether the given character is an uppercase letter (A-Z).
+ *
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is an upper-case letter, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is an uppercase letter, false otherwise.
*/
bool isUpper(int c);
@@ -226,8 +252,9 @@ bool isUpper(int c);
* If the parameter is outside the range of a signed or unsigned char, then
* false is returned.
*
- * @param c the character to test
- * @return true if the character is printable, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is printable, false otherwise.
*/
bool isPrint(int c);
@@ -235,36 +262,41 @@ bool isPrint(int c);
* Test whether the given character is a punctuation character,
* (i.e. not alphanumeric).
*
- * @param c the character to test
- * @return true if the character is punctuation, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is punctuation, false otherwise.
*/
bool isPunct(int c);
/**
* Test whether the given character is a control character.
*
- * @param c the character to test
- * @return true if the character is a control character, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a control character, false otherwise.
*/
bool isCntrl(int c);
/**
* Test whether the given character has a graphical representation.
*
- * @param c the character to test
- * @return true if the character is a graphic, false otherwise.
+ * @param c The character to test.
+ *
+ * @return True if the character is a graphic, false otherwise.
*/
bool isGraph(int c);
/**
- * Represent bytes size of a file as a number with floating point and
+ * Represent the size of a file in bytes as a number with floating point and
* largest suitable units. For example, 1474560 bytes as 1.4 MB.
*
- * @param bytes size in bytes to be represented
- * @param unitsOut (out-parameter) string with units
- * @note use _() to translate units correctly
- * @return string with a floating point number representing given size
+ * @param[in] bytes Size in bytes to be represented.
+ * @param[out] unitsOut String with units.
+ *
+ * @note Use @c _() to translate units correctly.
+ *
+ * @return String with a floating point number representing the given size.
*/
Common::String getHumanReadableBytes(uint64 bytes, Common::String &unitsOut);
More information about the Scummvm-git-logs
mailing list