[Scummvm-git-logs] scummvm master -> 3ff21ad8c281bdaf026110e8fb705ab3cd60a0d7
criezy
criezy at scummvm.org
Sat Nov 7 18:22:44 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:
3ff21ad8c2 DOXYGEN: Further doc updates in high priority files
Commit: 3ff21ad8c281bdaf026110e8fb705ab3cd60a0d7
https://github.com/scummvm/scummvm/commit/3ff21ad8c281bdaf026110e8fb705ab3cd60a0d7
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-11-07T18:19:09Z
Commit Message:
DOXYGEN: Further doc updates in high priority files
Adding, editing, updating doxygen comments in header files:
- common/archive.h
- common/array.h
- common/config-manager.h
- common/list.h
- common/random.h
- common/rect.h
- common/savefile.h
Changed paths:
common/archive.h
common/array.h
common/config-manager.h
common/list.h
common/random.h
common/rect.h
common/savefile.h
diff --git a/common/archive.h b/common/archive.h
index 6387753a16..5e4794fc10 100644
--- a/common/archive.h
+++ b/common/archive.h
@@ -56,13 +56,16 @@ class ArchiveMember {
public:
virtual ~ArchiveMember() { }
virtual SeekableReadStream *createReadStream() const = 0; /*!< Create a read stream. */
- virtual String getName() const = 0; /*!< Get the name of a read stream. */
- virtual String getDisplayName() const { return getName(); } /*!< Get display name of a read stream. */
+ virtual String getName() const = 0; /*!< Get the name of the archive member. */
+ virtual String getDisplayName() const { return getName(); } /*!< Get the display name of the archive member. */
};
-typedef SharedPtr<ArchiveMember> ArchiveMemberPtr;
-typedef List<ArchiveMemberPtr> ArchiveMemberList;
+typedef SharedPtr<ArchiveMember> ArchiveMemberPtr; /*!< Shared pointer to an archive member. */
+typedef List<ArchiveMemberPtr> ArchiveMemberList; /*!< List of archive members. */
+/**
+ * Compare two archive member operators @p a and @p b and return which of them is higher.
+ */
struct ArchiveMemberListComparator {
bool operator()(const ArchiveMemberPtr &a, const ArchiveMemberPtr &b) {
return a->getName() < b->getName();
@@ -84,9 +87,9 @@ class GenericArchiveMember : public ArchiveMember {
const Archive *_parent;
const String _name;
public:
- GenericArchiveMember(const String &name, const Archive *parent); /*!< Create a generic archive member. */
+ GenericArchiveMember(const String &name, const Archive *parent); /*!< Create a generic archive member that belongs to the @p parent archive. */
String getName() const; /*!< Get the name of a generic archive member. */
- SeekableReadStream *createReadStream() const;
+ SeekableReadStream *createReadStream() const; /*!< Create a read stream. */
};
@@ -100,7 +103,7 @@ public:
virtual ~Archive() { }
/**
- * Check if a member with the given name is present in the Archive.
+ * Check if a member with the given @p name is present in the Archive.
* Patterns are not allowed, as this is meant to be a quick File::exists()
* replacement.
*/
@@ -161,7 +164,7 @@ class SearchSet : public Archive {
ArchiveNodeList::iterator find(const String &name);
ArchiveNodeList::const_iterator find(const String &name) const;
- void insert(const Node& node); //!< Add an archive keeping the list sorted by descending priority.
+ void insert(const Node& node); //!< Add an archive while keeping the list sorted by descending priority.
bool _ignoreClashes;
@@ -175,12 +178,12 @@ public:
void add(const String& name, Archive *arch, int priority = 0, bool autoFree = true);
/**
- * Create and add a FSDirectory by name.
+ * Create and add an FSDirectory by name.
*/
void addDirectory(const String &name, const String &directory, int priority = 0, int depth = 1, bool flat = false);
/**
- * Create and add a FSDirectory by FSNode.
+ * Create and add an FSDirectory by FSNode.
*/
void addDirectory(const String &name, const FSNode &directory, int priority = 0, int depth = 1, bool flat = false);
@@ -262,7 +265,7 @@ public:
/**
* Ignore clashes when adding directories. For more details, see the corresponding parameter
- * in FSDirectory documentation.
+ * in @ref FSDirectory documentation.
*/
void setIgnoreClashes(bool ignoreClashes) { _ignoreClashes = ignoreClashes; }
};
diff --git a/common/array.h b/common/array.h
index 7613d72674..934d883813 100644
--- a/common/array.h
+++ b/common/array.h
@@ -47,7 +47,7 @@ namespace Common {
* can be accessed similarly to a regular C++ array. Accessing
* elements is performed in constant time (like with plain arrays).
* In addition, you can append, insert, and remove entries (this
- * is the 'dynamic' part). Doing that in general takes time
+ * is the 'dynamic' part). In general, doing that takes time
* proportional to the number of elements in the array.
*
* The container class closest to this in the C++ standard library is
@@ -56,23 +56,23 @@ namespace Common {
template<class T>
class Array {
public:
- typedef T *iterator;
- typedef const T *const_iterator;
+ typedef T *iterator; /*!< Array iterator. */
+ typedef const T *const_iterator; /*!< Const-qualified array iterator. */
- typedef T value_type;
+ typedef T value_type; /*!< Value type of the array. */
- typedef uint size_type;
+ typedef uint size_type; /*!< Size type of the array. */
protected:
- size_type _capacity;
- size_type _size;
- T *_storage;
+ size_type _capacity; /*!< Maximum number of elements the array can hold. */
+ size_type _size; /*!< How many elements the array holds. */
+ T *_storage; /*!< Memory used for element storage. */
public:
Array() : _capacity(0), _size(0), _storage(nullptr) {}
/**
- * Construct an array with `count` default-inserted instances of @p T. No
+ * Construct an array with @p count default-inserted instances of @p T. No
* copies are made.
*/
explicit Array(size_type count) : _size(count) {
@@ -82,13 +82,16 @@ public:
}
/**
- * Construct an array with `count` copies of elements with value `value`.
+ * Construct an array with @p count copies of elements with value @p value.
*/
Array(size_type count, const T &value) : _size(count) {
allocCapacity(count);
uninitialized_fill_n(_storage, count, value);
}
+ /**
+ * Construct an array as a copy of the given @p array.
+ */
Array(const Array<T> &array) : _capacity(array._size), _size(array._size), _storage(nullptr) {
if (array._storage) {
allocCapacity(_size);
@@ -98,7 +101,7 @@ public:
#ifdef USE_CXX11
/**
- * Constructs an array as a copy of the given array using the c++11 move semantic.
+ * Construct an array as a copy of the given array using the C++11 move semantic.
*/
Array(Array<T> &&old) : _capacity(old._capacity), _size(old._size), _storage(old._storage) {
old._storage = nullptr;
@@ -107,7 +110,14 @@ public:
}
/**
- * Constructs an array using list initialization.
+ * Construct an array using list initialization.
+ * For example:
+ * @code
+ * Common::Array<int> myArray = {1, 7, 42};
+ * @endcode
+ * constructs an array with 3 elements whose values are 1, 7, and 42 respectively.
+ * @note
+ * This constructor is only available when C++11 support is enabled.
*/
Array(std::initializer_list<T> list) : _size(list.size()) {
allocCapacity(list.size());
@@ -191,12 +201,13 @@ public:
return _storage[_size-1];
}
-
+ /** Insert an element into the array at the given position. */
void insert_at(size_type idx, const T &element) {
assert(idx <= _size);
insert_aux(_storage + idx, &element, &element + 1);
}
-
+
+ /** Insert copies of all the elements from the given array into this array at the given position. */
void insert_at(size_type idx, const Array<T> &array) {
assert(idx <= _size);
insert_aux(_storage + idx, array.begin(), array.end());
@@ -208,7 +219,8 @@ public:
void insert(iterator pos, const T &element) {
insert_aux(pos, &element, &element + 1);
}
-
+
+ /** Remove an element at the given position from the array and return the value of that element. */
T remove_at(size_type idx) {
assert(idx < _size);
T tmp = _storage[idx];
@@ -221,16 +233,19 @@ public:
// TODO: insert, remove, ...
+ /** Return a reference to the element at the given position in the array. */
T &operator[](size_type idx) {
assert(idx < _size);
return _storage[idx];
}
+ /** Return a const reference to the element at the given position in the array. */
const T &operator[](size_type idx) const {
assert(idx < _size);
return _storage[idx];
}
+ /** Assign the given @p array to this array. */
Array<T> &operator=(const Array<T> &array) {
if (this == &array)
return *this;
@@ -244,6 +259,7 @@ public:
}
#ifdef USE_CXX11
+ /** Assign the given array to this array using the C++11 move semantic. */
Array &operator=(Array<T> &&old) {
if (this == &old)
return *this;
@@ -261,10 +277,12 @@ public:
}
#endif
+ /** Return the size of the array. */
size_type size() const {
return _size;
}
+ /** Clear the array of all its elements. */
void clear() {
freeStorage(_storage, _size);
_storage = nullptr;
@@ -272,6 +290,7 @@ public:
_capacity = 0;
}
+ /** Erase the element at @p pos position and return an iterator pointing to the next element in the array. */
iterator erase(iterator pos) {
copy(pos + 1, _storage + _size, pos);
_size--;
@@ -279,11 +298,13 @@ public:
_storage[_size].~T();
return pos;
}
-
+
+ /** Check whether the array is empty. */
bool empty() const {
return (_size == 0);
}
+ /** Check whether two arrays are identical. */
bool operator==(const Array<T> &other) const {
if (this == &other)
return true;
@@ -296,26 +317,34 @@ public:
return true;
}
+ /** Check if two arrays are different. */
bool operator!=(const Array<T> &other) const {
return !(*this == other);
}
+ /** Return an iterator pointing to the first element in the array. */
iterator begin() {
return _storage;
}
+ /** Return an iterator pointing past the last element in the array. */
iterator end() {
return _storage + _size;
}
+ /** Return a const iterator pointing to the first element in the array. */
const_iterator begin() const {
return _storage;
}
+ /** Return a const iterator pointing past the last element in the array. */
const_iterator end() const {
return _storage + _size;
}
+ /** Reserve enough memory in the array so that it can store at least the given number of elements.
+ * The current content of the array is not modified.
+ */
void reserve(size_type newCapacity) {
if (newCapacity <= _capacity)
return;
@@ -330,6 +359,7 @@ public:
}
}
+ /** Change the size of the array. */
void resize(size_type newSize) {
reserve(newSize);
for (size_type i = newSize; i < _size; ++i)
@@ -339,6 +369,9 @@ public:
_size = newSize;
}
+ /** Assign to this array the elements between the given iterators from another array,
+ * from @p first included to @p last excluded.
+ */
void assign(const_iterator first, const_iterator last) {
resize(distance(first, last)); // FIXME: ineffective?
T *dst = _storage;
@@ -347,15 +380,17 @@ public:
}
protected:
+ /** Round up capacity to the next power of 2.
+ * A minimal capacity of 8 is used.
+ */
static size_type roundUpCapacity(size_type capacity) {
- // Round up capacity to the next power of 2;
- // we use a minimal capacity of 8.
size_type capa = 8;
while (capa < capacity)
capa <<= 1;
return capa;
}
+ /** Allocate a specific capacity for the array. */
void allocCapacity(size_type capacity) {
_capacity = capacity;
if (capacity) {
@@ -367,6 +402,7 @@ protected:
}
}
+ /** Free the storage used by the array. */
void freeStorage(T *storage, const size_type elements) {
for (size_type i = 0; i < elements; ++i)
storage[i].~T();
diff --git a/common/config-manager.h b/common/config-manager.h
index 07cb73b949..7e201b4ca9 100644
--- a/common/config-manager.h
+++ b/common/config-manager.h
@@ -35,7 +35,7 @@ namespace Common {
* @defgroup common_config Configuration manager
* @ingroup common
*
- * @brief The (singleton) configuration manager, used to query & set configuration
+ * @brief The (singleton) configuration manager, used to query and set configuration
* values using string keys.
*
* @{
@@ -60,38 +60,50 @@ public:
private:
StringMap _entries;
StringMap _keyValueComments;
- String _domainComment;
+ String _domainComment;
public:
typedef StringMap::const_iterator const_iterator;
- const_iterator begin() const { return _entries.begin(); }
- const_iterator end() const { return _entries.end(); }
-
- bool empty() const { return _entries.empty(); }
-
- bool contains(const String &key) const { return _entries.contains(key); }
-
- String &operator[](const String &key) { return _entries[key]; }
- const String &operator[](const String &key) const { return _entries[key]; }
-
- void setVal(const String &key, const String &value) { _entries.setVal(key, value); }
-
- String &getVal(const String &key) { return _entries.getVal(key); }
- const String &getVal(const String &key) const { return _entries.getVal(key); }
- bool tryGetVal(const String &key, String &out) const { return _entries.tryGetVal(key, out); }
-
- void clear() { _entries.clear(); }
-
- void erase(const String &key) { _entries.erase(key); }
-
- void setDomainComment(const String &comment);
- const String &getDomainComment() const;
-
- void setKVComment(const String &key, const String &comment);
- const String &getKVComment(const String &key) const;
- bool hasKVComment(const String &key) const;
+ const_iterator begin() const { return _entries.begin(); } /*!< Return the beginning position of configuration entries. */
+ const_iterator end() const { return _entries.end(); } /*!< Return the ending position of configuration entries. */
+
+ bool empty() const { return _entries.empty(); } /*!< Return true if the configuration is empty, i.e. has no [key, value] pairs, and false otherwise. */
+
+ bool contains(const String &key) const { return _entries.contains(key); } /*!< Check whether the domain contains a @p key. */
+ /** Return the configuration value for the given key.
+ * If no entry exists for the given key in the configuration, it is created.
+ */
+ String &operator[](const String &key) { return _entries[key]; }
+ /** Return the configuration value for the given key.
+ * @note This function does *not* create a configuration entry
+ * for the given key if it does not exist.
+ */
+ const String &operator[](const String &key) const { return _entries[key]; }
+
+ void setVal(const String &key, const String &value) { _entries.setVal(key, value); } /*!< Assign a @p value to a @p key. */
+
+ String &getVal(const String &key) { return _entries.getVal(key); } /*!< Retrieve the value of a @p key. */
+ const String &getVal(const String &key) const { return _entries.getVal(key); } /*!< @overload */
+ /**
+ * Retrieve the value of @p key if it exists and leave the referenced variable unchanged if the key does not exist.
+ * @return True if the key exists, false otherwise.
+ * You can use this method if you frequently attempt to access keys that do not exist.
+ */
+ bool tryGetVal(const String &key, String &out) const { return _entries.tryGetVal(key, out); }
+
+ void clear() { _entries.clear(); } /*!< Clear all configuration entries in the domain. */
+
+ void erase(const String &key) { _entries.erase(key); } /*!< Remove a key from the domain. */
+
+ void setDomainComment(const String &comment); /*!< Add a @p comment for this configuration domain. */
+ const String &getDomainComment() const; /*!< Retrieve the comment of this configuration domain. */
+
+ void setKVComment(const String &key, const String &comment); /*!< Add a key-value @p comment to a @p key. */
+ const String &getKVComment(const String &key) const; /*!< Retrieve the key-value comment of a @p key. */
+ bool hasKVComment(const String &key) const; /*!< Check whether a @p key has a key-value comment. */
};
-
+
+ /** A hash map of existing configuration domains. */
typedef HashMap<String, Domain, IgnoreCase_Hash, IgnoreCase_EqualTo> DomainMap;
/** The name of the application domain (normally 'scummvm'). */
@@ -100,11 +112,11 @@ public:
/** The transient (pseudo) domain. */
static char const *const kTransientDomain;
- /** The name of keymapper domain used to store the key maps */
+ /** The name of keymapper domain used to store the key maps. */
static char const *const kKeymapperDomain;
#ifdef USE_CLOUD
- /** The name of cloud domain used to store user's tokens */
+ /** The name of cloud domain used to store the user's tokens. */
static char const *const kCloudDomain;
#endif
@@ -127,9 +139,9 @@ public:
* @{
*/
- bool hasKey(const String &key) const;
- const String & get(const String &key) const;
- void set(const String &key, const String &value);
+ bool hasKey(const String &key) const; /*!< Check if a given @p key exists. */
+ const String &get(const String &key) const; /*!< Get the value of a @p key. */
+ void set(const String &key, const String &value); /*!< Assign a @p value to a @p key. */
/** @} */
/**
@@ -149,11 +161,11 @@ public:
* @{
*/
- bool hasKey(const String &key, const String &domName) const;
- const String & get(const String &key, const String &domName) const;
- void set(const String &key, const String &value, const String &domName);
+ bool hasKey(const String &key, const String &domName) const; /*!< Check if a given @p key exists in the @p domName domain. */
+ const String &get(const String &key, const String &domName) const; /*!< Get the value of a @p key from the @p domName domain. */
+ void set(const String &key, const String &value, const String &domName); /*!< Assign a @p value to a @p key in the @p domName domain. */
- void removeKey(const String &key, const String &domName);
+ void removeKey(const String &key, const String &domName); /*!< Remove a @p key to a @p key from the @p domName domain. */
/** @} */
#endif
@@ -165,13 +177,12 @@ public:
int getInt(const String &key, const String &domName = String()) const; /*!< Get integer value. */
bool getBool(const String &key, const String &domName = String()) const; /*!< Get Boolean value. */
void setInt(const String &key, int value, const String &domName = String()); /*!< Set integer value. */
- void setBool(const String &key, bool value, const String &domName = String()); /*!< Set integer value. */
-
+ void setBool(const String &key, bool value, const String &domName = String()); /*!< Set Boolean value. */
- void registerDefault(const String &key, const String &value);
- void registerDefault(const String &key, const char *value);
- void registerDefault(const String &key, int value);
- void registerDefault(const String &key, bool value);
+ void registerDefault(const String &key, const String &value); /*!< Register a value as the default. */
+ void registerDefault(const String &key, const char *value); /*!< @overload */
+ void registerDefault(const String &key, int value); /*!< @overload */
+ void registerDefault(const String &key, bool value); /*!< @overload */
void flushToDisk(); /*!< Flush configuration to disk. */
@@ -188,15 +199,15 @@ public:
void removeMiscDomain(const String &domName); /*!< Remove a miscellaneous domain. */
void renameMiscDomain(const String &oldName, const String &newName); /*!< Rename a miscellaneous domain. */
- bool hasGameDomain(const String &domName) const;
- bool hasMiscDomain(const String &domName) const;
+ bool hasGameDomain(const String &domName) const; /*!< Check if a specific game domain exists in the DomainMap. */
+ bool hasMiscDomain(const String &domName) const; /*!< Check if a specific miscellaneous domain exists in the DomainMap. */
- const DomainMap & getGameDomains() const { return _gameDomains; }
- DomainMap::iterator beginGameDomains() { return _gameDomains.begin(); }
- DomainMap::iterator endGameDomains() { return _gameDomains.end(); }
+ const DomainMap &getGameDomains() const { return _gameDomains; } /*!< Return all game domains in the DomainMap. */
+ DomainMap::iterator beginGameDomains() { return _gameDomains.begin(); } /*!< Return the beginning position of game domains. */
+ DomainMap::iterator endGameDomains() { return _gameDomains.end(); } /*!< Return the ending position of game domains. */
- static void defragment(); // move in memory to reduce fragmentation
- void copyFrom(ConfigManager &source);
+ static void defragment(); /*!< Move the configuration in memory to reduce fragmentation. */
+ void copyFrom(ConfigManager &source); /*!< Copy from a ConfigManager instance. */
/** @} */
private:
friend class Singleton<SingletonBaseType>;
diff --git a/common/list.h b/common/list.h
index f889dbc9cb..fd1347fa82 100644
--- a/common/list.h
+++ b/common/list.h
@@ -31,37 +31,40 @@ namespace Common {
* @defgroup common_list Lists
* @ingroup common
*
- * @brief API and templates for managing lists.
+ * @brief API for managing doubly linked lists.
*
*
* @{
*/
/**
- * Simple double linked list, modeled after the list template of the standard
+ * Simple doubly linked list, modeled after the list template of the standard
* C++ library.
*/
template<typename t_T>
class List {
protected:
- typedef ListInternal::NodeBase NodeBase;
- typedef ListInternal::Node<t_T> Node;
+ typedef ListInternal::NodeBase NodeBase; /*!< @todo Doc required. */
+ typedef ListInternal::Node<t_T> Node; /*!< An element of the doubly linked list. */
- NodeBase _anchor;
+ NodeBase _anchor; /*!< Pointer to the position of the element in the list. */
public:
- typedef ListInternal::Iterator<t_T> iterator;
- typedef ListInternal::ConstIterator<t_T> const_iterator;
+ typedef ListInternal::Iterator<t_T> iterator; /*!< List iterator. */
+ typedef ListInternal::ConstIterator<t_T> const_iterator; /*!< Const-qualified list iterator. */
- typedef t_T value_type;
- typedef uint size_type;
+ typedef t_T value_type; /*!< Value type of the list. */
+ typedef uint size_type; /*!< Size type of the list. */
public:
+ /**
+ * Construct a new empty list.
+ */
List() {
_anchor._prev = &_anchor;
_anchor._next = &_anchor;
}
- List(const List<t_T> &list) {
+ List(const List<t_T> &list) { /*!< Construct a new list as a copy of the given @p list. */
_anchor._prev = &_anchor;
_anchor._next = &_anchor;
@@ -73,14 +76,14 @@ public:
}
/**
- * Inserts element before pos.
+ * Insert an @p element before @p pos.
*/
void insert(iterator pos, const t_T &element) {
insert(pos._node, element);
}
/**
- * Inserts the elements from first to last before pos.
+ * Insert elements from @p first to @p last before @p pos.
*/
template<typename iterator2>
void insert(iterator pos, iterator2 first, iterator2 last) {
@@ -89,8 +92,8 @@ public:
}
/**
- * Deletes the element at location pos and returns an iterator pointing
- * to the element after the one which was deleted.
+ * Delete the element at location @p pos and return an iterator pointing
+ * to the element after the one that was deleted.
*/
iterator erase(iterator pos) {
assert(pos != end());
@@ -98,8 +101,8 @@ public:
}
/**
- * Deletes the element at location pos and returns an iterator pointing
- * to the element before the one which was deleted.
+ * Delete the element at location @p pos and return an iterator pointing
+ * to the element before the one that was deleted.
*/
iterator reverse_erase(iterator pos) {
assert(pos != end());
@@ -107,9 +110,9 @@ public:
}
/**
- * Deletes the elements between first and last (including first but not
- * last) and returns an iterator pointing to the element after the one
- * which was deleted (i.e., last).
+ * Delete the elements between @p first and @p last (including @p first but not
+ * @p last). Return an iterator pointing to the element after the one
+ * that was deleted (that is, @p last).
*/
iterator erase(iterator first, iterator last) {
NodeBase *f = first._node;
@@ -120,7 +123,7 @@ public:
}
/**
- * Removes all elements that are equal to val from the list.
+ * Remove all elements that are equal to @p val from the list.
*/
void remove(const t_T &val) {
NodeBase *i = _anchor._next;
@@ -131,48 +134,49 @@ public:
i = i->_next;
}
- /** Inserts element at the start of the list. */
+ /** Insert an @p element at the start of the list. */
void push_front(const t_T &element) {
insert(_anchor._next, element);
}
- /** Appends element to the end of the list. */
+ /** Append an @p element to the end of the list. */
void push_back(const t_T &element) {
insert(&_anchor, element);
}
- /** Removes the first element of the list. */
+ /** Remove the first element of the list. */
void pop_front() {
assert(!empty());
erase(_anchor._next);
}
- /** Removes the last element of the list. */
+ /** Remove the last element of the list. */
void pop_back() {
assert(!empty());
erase(_anchor._prev);
}
- /** Returns a reference to the first element of the list. */
+ /** Return a reference to the first element of the list. */
t_T &front() {
return static_cast<Node *>(_anchor._next)->_data;
}
- /** Returns a reference to the first element of the list. */
+ /** Return a reference to the first element of the list. */
const t_T &front() const {
return static_cast<Node *>(_anchor._next)->_data;
}
- /** Returns a reference to the last element of the list. */
+ /** Return a reference to the last element of the list. */
t_T &back() {
return static_cast<Node *>(_anchor._prev)->_data;
}
- /** Returns a reference to the last element of the list. */
+ /** Return a reference to the last element of the list. */
const t_T &back() const {
return static_cast<Node *>(_anchor._prev)->_data;
}
+ /** Assign a given @p list to this list. */
List<t_T> &operator=(const List<t_T> &list) {
if (this != &list) {
iterator i;
@@ -193,6 +197,7 @@ public:
return *this;
}
+ /** Return the size of the list. */
size_type size() const {
size_type n = 0;
for (const NodeBase *cur = _anchor._next; cur != &_anchor; cur = cur->_next)
@@ -200,6 +205,7 @@ public:
return n;
}
+ /** Remove all elements from the list. */
void clear() {
NodeBase *pos = _anchor._next;
while (pos != &_anchor) {
@@ -212,36 +218,57 @@ public:
_anchor._next = &_anchor;
}
+ /** Check whether the list is empty. */
bool empty() const {
return (&_anchor == _anchor._next);
}
-
+ /** Return an iterator to the start of the list.
+ * This can be used, for example, to iterate from the first element
+ * of the list to the last element of the list.
+ */
iterator begin() {
return iterator(_anchor._next);
}
+ /** Return a reverse iterator to the start of the list.
+ * This can be used, for example, to iterate from the last element
+ * of the list to the first element of the list.
+ */
iterator reverse_begin() {
return iterator(_anchor._prev);
}
+ /** Return an iterator to the end of the list. */
iterator end() {
return iterator(&_anchor);
}
+ /** Return a const iterator to the start of the list.
+ * This can be used, for example, to iterate from the first element
+ * of the list to the last element of the list.
+ */
const_iterator begin() const {
return const_iterator(_anchor._next);
}
+ /** Return a const reverse iterator to the start of the list.
+ * This can be used, for example, to iterate from the last element
+ * of the list to the first element of the list.
+ */
const_iterator reverse_begin() const {
return const_iterator(_anchor._prev);
}
+ /** Return a const iterator to the end of the list. */
const_iterator end() const {
return const_iterator(const_cast<NodeBase *>(&_anchor));
}
protected:
+ /**
+ * Erase an element at @p pos.
+ */
NodeBase erase(NodeBase *pos) {
NodeBase n = *pos;
Node *node = static_cast<Node *>(pos);
@@ -252,7 +279,7 @@ protected:
}
/**
- * Inserts element before pos.
+ * Insert an @p element before @p pos.
*/
void insert(NodeBase *pos, const t_T &element) {
ListInternal::NodeBase *newNode = new Node(element);
diff --git a/common/random.h b/common/random.h
index 90422e328e..e67183ed64 100644
--- a/common/random.h
+++ b/common/random.h
@@ -48,38 +48,38 @@ private:
public:
/**
- * Construct a new randomness source with the specific name.
- * The name used name must be globally unique, and is used to
+ * Construct a new randomness source with the specific @p name.
+ * The name used must be globally unique, and is used to
* register the randomness source with the active event recorder,
* if any.
*/
RandomSource(const String &name);
- void setSeed(uint32 seed);
+ void setSeed(uint32 seed); /*!< Set the seed used to initialize the RNG. */
- uint32 getSeed() const {
+ uint32 getSeed() const { /*!< Get a random seed that can be used to initialize the RNG. */
return _randSeed;
}
/**
- * Generates a random unsigned integer in the interval [0, max].
- * @param max the upper bound
- * @return a random number in the interval [0, max]
+ * Generate a random unsigned integer in the interval [0, max].
+ * @param max The upper bound
+ * @return A random number in the interval [0, max].
*/
uint getRandomNumber(uint max);
/**
- * Generates a random bit, i.e. either 0 or 1.
- * Identical to getRandomNumber(1), but potentially faster.
- * @return a random bit, either 0 or 1
+ * Generate a random bit, i.e. either 0 or 1.
+ * Identical to @c getRandomNumber(1), but potentially faster.
+ * @return A random bit, either 0 or 1.
*/
uint getRandomBit();
/**
- * Generates a random unsigned integer in the interval [min, max].
- * @param min the lower bound
- * @param max the upper bound
- * @return a random number in the interval [min, max]
+ * Generate a random unsigned integer in the interval [min, max].
+ * @param min The lower bound.
+ * @param max The upper bound.
+ * @return A random number in the interval [min, max].
*/
uint getRandomNumberRng(uint min, uint max);
diff --git a/common/rect.h b/common/rect.h
index f43aa69e40..8585accbb1 100644
--- a/common/rect.h
+++ b/common/rect.h
@@ -44,35 +44,69 @@ namespace Common {
* Simple class for handling both 2D position and size.
*/
struct Point {
- int16 x; ///< The horizontal part of the point
- int16 y; ///< The vertical part of the point
+ int16 x; /*!< The horizontal position of the point. */
+ int16 y; /*!< The vertical position of the point. */
Point() : x(0), y(0) {}
+
+ /**
+ * Create a point with position defined by @p x1 and @p y1.
+ */
Point(int16 x1, int16 y1) : x(x1), y(y1) {}
+ /**
+ * Determine whether the position of two points is the same.
+ */
bool operator==(const Point &p) const { return x == p.x && y == p.y; }
+ /**
+ * Determine whether the position of two points is not the same.
+ */
bool operator!=(const Point &p) const { return x != p.x || y != p.y; }
+ /**
+ * Create a point by adding the @p delta value to a point.
+ */
Point operator+(const Point &delta) const { return Point(x + delta.x, y + delta.y); }
+ /**
+ * Create a point by subtracting the @p delta value from a point.
+ */
Point operator-(const Point &delta) const { return Point(x - delta.x, y - delta.y); }
+ /**
+ * Create a point by dividing a point by the (int) @p divisor value.
+ */
Point operator/(int divisor) const { return Point(x / divisor, y / divisor); }
+ /**
+ * Create a point by multiplying a point by the (int) @p multiplier value.
+ */
Point operator*(int multiplier) const { return Point(x * multiplier, y * multiplier); }
+ /**
+ * Create a point by dividing a point by the (double) @p divisor value.
+ */
Point operator/(double divisor) const { return Point(x / divisor, y / divisor); }
+ /**
+ * Create a point by multiplying a point by the (double) @p multiplier value.
+ */
Point operator*(double multiplier) const { return Point(x * multiplier, y * multiplier); }
+ /**
+ * Change a point's position by adding @p delta to its x and y coordinates.
+ */
void operator+=(const Point &delta) {
x += delta.x;
y += delta.y;
}
+ /**
+ * Change a point's position by subtracting @p delta from its x and y arguments.
+ */
void operator-=(const Point &delta) {
x -= delta.x;
y -= delta.y;
}
/**
- * Return the square of the distance between this point and the point p.
+ * Return the square of the distance between this point and the point @p p.
*
- * @param p the other point
- * @return the distance between this and p
+ * @param p The other point.
+ * @return The distance between this and @p p.
*/
uint sqrDist(const Point &p) const {
int diffx = ABS(p.x - x);
@@ -95,9 +129,9 @@ static inline Point operator*(double multiplier, const Point &p) { return Point(
*
* Note: This implementation is built around the assumption that (top,left) is
* part of the rectangle, but (bottom,right) is not. This is reflected in
- * various methods, including contains(), intersects() and others.
+ * various methods, including contains(), intersects(), and others.
*
- * Another very wide spread approach to rectangle classes treats (bottom,right)
+ * Another very widespread approach to rectangle classes treats (bottom,right)
* also as a part of the rectangle.
*
* Conceptually, both are sound, but the approach we use saves many intermediate
@@ -109,91 +143,110 @@ static inline Point operator*(double multiplier, const Point &p) { return Point(
* When writing code using our Rect class, always keep this principle in mind!
*/
struct Rect {
- int16 top, left; ///< The point at the top left of the rectangle (part of the rect).
- int16 bottom, right; ///< The point at the bottom right of the rectangle (not part of the rect).
+ int16 top, left; /*!< The point at the top left of the rectangle (part of the Rect). */
+ int16 bottom, right; /*!< The point at the bottom right of the rectangle (not part of the Rect). */
Rect() : top(0), left(0), bottom(0), right(0) {}
+ /**
+ * Create a rectangle with the top-left corner at position (0, 0) and the given width @p w and height @p h.
+ */
Rect(int16 w, int16 h) : top(0), left(0), bottom(h), right(w) {}
+ /**
+ * Create a rectangle with the top-left corner at the given position (x1, y1)
+ * and the bottom-right corner at the position (x2, y2).
+ *
+ * The @p x2 value must be greater or equal @p x1 and @p y2 must be greater or equal @p y1.
+ */
Rect(int16 x1, int16 y1, int16 x2, int16 y2) : top(y1), left(x1), bottom(y2), right(x2) {
assert(isValidRect());
}
+ /**
+ * Check if two rectangles are identical.
+ *
+ * @return True if the rectangles are identical, false otherwise.
+ */
bool operator==(const Rect &rhs) const { return equals(rhs); }
+ /**
+ * Check if two rectangles are different.
+ *
+ * @return True if the rectangles are different, false otherwise.
+ */
bool operator!=(const Rect &rhs) const { return !equals(rhs); }
- int16 width() const { return right - left; }
- int16 height() const { return bottom - top; }
+ int16 width() const { return right - left; } /*!< Return the width of a rectangle. */
+ int16 height() const { return bottom - top; } /*!< Return the height of a rectangle. */
- void setWidth(int16 aWidth) {
+ void setWidth(int16 aWidth) { /*!< Set the width to @p aWidth value. */
right = left + aWidth;
}
- void setHeight(int16 aHeight) {
+ void setHeight(int16 aHeight) { /*!< Set the height to @p aHeight value. */
bottom = top + aHeight;
}
/**
- * Check if given position is inside this rectangle.
+ * Check if the given position is inside this rectangle.
*
- * @param x the horizontal position to check
- * @param y the vertical position to check
+ * @param x The horizontal position to check.
+ * @param y The vertical position to check.
*
- * @return true if the given position is inside this rectangle, false otherwise
+ * @return True if the given position is inside this rectangle, false otherwise.
*/
bool contains(int16 x, int16 y) const {
return (left <= x) && (x < right) && (top <= y) && (y < bottom);
}
/**
- * Check if given point is inside this rectangle.
+ * Check if the given point is inside this rectangle.
*
- * @param p the point to check
+ * @param p The point to check.
*
- * @return true if the given point is inside this rectangle, false otherwise
+ * @return True if the given point is inside this rectangle, false otherwise.
*/
bool contains(const Point &p) const {
return contains(p.x, p.y);
}
/**
- * Check if the given rect is contained inside this rectangle.
+ * Check if the given Rect is contained inside this rectangle.
*
- * @param r The rectangle to check
+ * @param r The rectangle to check.
*
- * @return true if the given rect is inside, false otherwise
+ * @return True if the given Rect is inside, false otherwise.
*/
bool contains(const Rect &r) const {
return (left <= r.left) && (r.right <= right) && (top <= r.top) && (r.bottom <= bottom);
}
/**
- * Check if the given rect is equal to this one.
+ * Check if the given Rect is equal to this one.
*
- * @param r The rectangle to check
+ * @param r The rectangle to check.
*
- * @return true if the given rect is equal, false otherwise
+ * @return true If the given Rect is equal, false otherwise.
*/
bool equals(const Rect &r) const {
return (left == r.left) && (right == r.right) && (top == r.top) && (bottom == r.bottom);
}
/**
- * Check if given rectangle intersects with this rectangle
+ * Check if the given rectangle intersects with this rectangle.
*
- * @param r the rectangle to check
+ * @param r The rectangle to check.
*
- * @return true if the given rectangle has a non-empty intersection with
- * this rectangle, false otherwise
+ * @return True if the given rectangle has a non-empty intersection with
+ * this rectangle, false otherwise.
*/
bool intersects(const Rect &r) const {
return (left < r.right) && (r.left < right) && (top < r.bottom) && (r.top < bottom);
}
/**
- * Find the intersecting rectangle between this rectangle and the given rectangle
+ * Find the intersecting rectangle between this rectangle and the given rectangle.
*
- * @param r the intersecting rectangle
+ * @param r The intersecting rectangle.
*
- * @return the intersection of the rectangles or an empty rectangle if not intersecting
+ * @return The intersection of the rectangles or an empty rectangle if not intersecting.
*/
Rect findIntersectingRect(const Rect &r) const {
if (!intersects(r))
@@ -203,9 +256,9 @@ struct Rect {
}
/**
- * Extend this rectangle so that it contains r
+ * Extend this rectangle so that it contains @p r.
*
- * @param r the rectangle to extend by
+ * @param r The rectangle to extend by.
*/
void extend(const Rect &r) {
left = MIN(left, r.left);
@@ -215,9 +268,9 @@ struct Rect {
}
/**
- * Extend this rectangle in all four directions by the given number of pixels
+ * Extend this rectangle in all four directions by the given number of pixels.
*
- * @param offset the size to grow by
+ * @param offset The size to grow by.
*/
void grow(int16 offset) {
top -= offset;
@@ -226,6 +279,9 @@ struct Rect {
right += offset;
}
+ /**
+ * Clip this rectangle with another rectangle @p r.
+ */
void clip(const Rect &r) {
assert(isValidRect());
assert(r.isValidRect());
@@ -243,18 +299,33 @@ struct Rect {
else if (right < r.left) right = r.left;
}
+ /**
+ * Reduce the dimensions of this rectangle by setting max width and max heigth.
+ */
void clip(int16 maxw, int16 maxh) {
clip(Rect(0, 0, maxw, maxh));
}
+ /**
+ * Check if the rectangle is empty (its width or length is 0) or invalid (its width or length are negative).
+ *
+ * @retval true The rectangle is empty or invalid.
+ * @retval false The rectangle is valid and not empty.
+ */
bool isEmpty() const {
return (left >= right || top >= bottom);
}
+ /**
+ * Check if this is a valid rectangle.
+ */
bool isValidRect() const {
return (left <= right && top <= bottom);
}
+ /**
+ * Move this rectangle to the position defined by @p x, @p y.
+ */
void moveTo(int16 x, int16 y) {
bottom += y - top;
right += x - left;
@@ -262,22 +333,31 @@ struct Rect {
left = x;
}
+ /**
+ * Move the rectangle by the given delta x and y values.
+ */
void translate(int16 dx, int16 dy) {
left += dx; right += dx;
top += dy; bottom += dy;
}
+ /**
+ * Move this rectangle to the position of the point @p p.
+ */
void moveTo(const Point &p) {
moveTo(p.x, p.y);
}
+ /**
+ * Print debug messages related to this class.
+ */
void debugPrint(int debuglevel = 0, const char *caption = "Rect:") const {
debug(debuglevel, "%s %d, %d, %d, %d", caption, left, top, right, bottom);
}
/**
* Create a rectangle around the given center.
- * @note the center point is rounded up and left when given an odd width and height
+ * @note The center point is rounded up and left when given an odd width and height.
*/
static Rect center(int16 cx, int16 cy, int16 w, int16 h) {
int x = cx - w / 2, y = cy - h / 2;
@@ -286,10 +366,10 @@ struct Rect {
/**
* Given target surface with size clip, this function ensures that
- * blit arguments dst, rect are within clip rectangle.
- * @param dst blit destination coordinates
- * @param rect blit source rectangle
- * @param clip clip rectangle (size of destination surface)
+ * blit arguments @p dst and @p rect are within the @p clip rectangle.
+ * @param dst Blit destination coordinates.
+ * @param rect Blit source rectangle.
+ * @param clip Clip rectangle (size of destination surface).
*/
static bool getBlitRect(Point &dst, Rect &rect, const Rect &clip) {
if (dst.x < clip.left) {
diff --git a/common/savefile.h b/common/savefile.h
index 8a1bd28553..03893ce1de 100644
--- a/common/savefile.h
+++ b/common/savefile.h
@@ -42,7 +42,7 @@ namespace Common {
/**
* A class which allows game engines to load game state data.
- * That typically means "save games", but also includes things like the
+ * This typically means "save games", but also includes things like the
* IQ points in Indy3.
*/
typedef SeekableReadStream InSaveFile;
@@ -54,48 +54,89 @@ typedef SeekableReadStream InSaveFile;
*/
class OutSaveFile: public WriteStream {
protected:
- WriteStream *_wrapped;
+ WriteStream *_wrapped; /*!< @todo Doc required. */
public:
- OutSaveFile(WriteStream *w);
+ OutSaveFile(WriteStream *w); /*!< Create an OutSaveFile that uses the given WriteStream to write the data. */
virtual ~OutSaveFile();
+ /**
+ * Return true if an I/O failure occurred.
+ * This flag is never cleared automatically. In order to clear it,
+ * you must call clearErr() explicitly.
+ */
virtual bool err() const;
+
+ /**
+ * Reset the I/O error status as returned by err().
+ */
virtual void clearErr();
+
+ /**
+ * Finalize and close this stream. To be called right before this
+ * stream instance is deleted. The goal here is to enable calling
+ * code to detect and handle I/O errors which might occur when
+ * closing (and flushing, if buffered) the stream.
+ *
+ * After this method has been called, no further writes may be
+ * performed on the stream. Calling err() is allowed.
+ *
+ * By default, this just flushes the stream.
+ */
virtual void finalize();
+
+ /**
+ * Commit any buffered data to the underlying channel or
+ * storage medium. Unbuffered streams can use the default
+ * implementation
+ */
virtual bool flush();
+
+ /**
+ * Write data into the stream.
+ *
+ * @param dataPtr Pointer to the data to be written.
+ * @param dataSize Number of bytes to be written.
+ */
virtual uint32 write(const void *dataPtr, uint32 dataSize);
+
+ /**
+ * Obtain the current value of the stream position indicator of the
+ * stream.
+ *
+ * @return The current position indicator, or -1 if an error occurred.
+ */
virtual int32 pos() const;
};
/**
- * The SaveFileManager is serving as a factory for InSaveFile
+ * The SaveFileManager serves as a factory for InSaveFile
* and OutSaveFile objects.
*
* Engines and other code should use SaveFiles whenever they need to
- * store data which they need to be able to retrieve again later on --
+ * store data that they need to retrieve again later on --
* i.e. typically save states, but also configuration files and similar
- * things.
+ * objects.
*
- * Savefile names represent SaveFiles. These names are case insensitive, that
- * means a name of "Kq1.000" represents the same savefile as "kq1.000". In
- * addition, SaveFileManager does not allow for names which contain path
- * separators like '/' or '\'. This is because we do not support directories
+ * Save file names represent SaveFiles. These names are case insensitive. That
+ * means a name of "Kq1.000" represents the same save file as "kq1.000". In
+ * addition, SaveFileManager does not allow for names that contain path
+ * separators like '/' or '\'. This is because directories are not supported
* in SaveFileManager.
*
* While not declared as a singleton, it is effectively used as such,
- * with OSystem::getSavefileManager returning a pointer to the single
+ * with OSystem::getSavefileManager returning a pointer to single
* SaveFileManager instances to be used.
*/
class SaveFileManager : NonCopyable {
protected:
- Error _error;
- String _errorDesc;
+ Error _error; /*!< Error code. */
+ String _errorDesc; /*!< Description of an error. */
/**
- * Set some information about the last error which occurred .
- * @param error Code identifying the last error.
+ * Set some information about the last error that occurred.
+ * @param error Code identifying the last error.
* @param errorDesc String describing the last error.
*/
virtual void setError(Error error, const String &errorDesc) { _error = error; _errorDesc = errorDesc; }
@@ -104,114 +145,114 @@ public:
virtual ~SaveFileManager() {}
/**
- * Clears the last set error code and string.
+ * Clear the last set error code and string.
*/
virtual void clearError() { _error = kNoError; _errorDesc.clear(); }
/**
- * Returns the last occurred error code. If none occurred, returns kNoError.
+ * Return the last occurred error code. If none occurred, return kNoError.
*
* @return A value indicating the type of the last error.
*/
virtual Error getError() { return _error; }
/**
- * Returns the last occurred error description. If none occurred, returns 0.
+ * Return the last occurred error description. If none occurred, return 0.
*
* @return A string describing the last error.
*/
virtual String getErrorDesc() { return _errorDesc; }
/**
- * Returns the last occurred error description. If none occurred, returns 0.
- * Also clears the last error state and description.
+ * Return the last occurred error description. If none occurred, return 0.
+ * Also, clear the last error state and description.
*
* @return A string describing the last error.
*/
virtual String popErrorDesc();
/**
- * Open the savefile with the specified name in the given directory for
+ * Open the save file with the specified @p name in the given directory for
* saving.
*
* Saved games are compressed by default, and engines are expected to
* always write compressed saves.
*
- * A notable exception is if uncompressed files are needed for
+ * A notable exception is when uncompressed files are needed for
* compatibility with games not supported by ScummVM, such as character
- * exports from the Quest for Glory series. QfG5 is a 3D game and won't be
+ * exports from the Quest for Glory series. QfG5 is a 3D game and will not be
* supported by ScummVM.
*
- * @param name The name of the savefile.
- * @param compress Toggles whether to compress the resulting save file
- * (default) or not.
+ * @param name Name of the save file.
+ * @param compress Whether to compress the resulting save file (default) or not.
+ *
* @return Pointer to an OutSaveFile, or NULL if an error occurred.
*/
virtual OutSaveFile *openForSaving(const String &name, bool compress = true) = 0;
/**
- * Open the file with the specified name in the given directory for loading.
+ * Open the file with the specified @p name in the given directory for loading.
*
- * @param name The name of the savefile.
+ * @param name Name of the save file.
* @return Pointer to an InSaveFile, or NULL if an error occurred.
*/
virtual InSaveFile *openForLoading(const String &name) = 0;
/**
* Open the file with the specified name in the given directory for loading.
- * In contrast to openForLoading(), it returns raw file instead of unpacked.
+ * In contrast to openForLoading(), it returns a raw file instead of unpacked.
*
- * @param name The name of the savefile.
+ * @param name Name of the save file.
* @return Pointer to an InSaveFile, or NULL if an error occurred.
*/
virtual InSaveFile *openRawFile(const String &name) = 0;
/**
- * Removes the given savefile from the system.
+ * Remove the given save file from the system.
*
- * @param name The name of the savefile to be removed.
- * @return true if no error occurred, false otherwise.
+ * @param name Name of the save file to be removed.
+ * @return True if no error occurred, false otherwise.
*/
virtual bool removeSavefile(const String &name) = 0;
/**
- * Renames the given savefile.
+ * Rename the given save file.
*
- * @param oldName Old name.
- * @param newName New name.
- * @param compress Toggles whether to compress the resulting save file
- * (default) or not.
- * @return true if no error occurred. false otherwise.
+ * @param oldName Old name.
+ * @param newName New name.
+ * @param compress Whether to compress the resulting save file (default) or not.
+ *
+ * @return True if no error occurred, false otherwise.
*/
virtual bool renameSavefile(const String &oldName, const String &newName, bool compress = true);
/**
- * Copy the given savefile.
+ * Copy the given save file.
*
- * @param oldName Old name.
- * @param newName New name.
- * @param compress Toggles whether to compress the resulting save file
- * (default) or not.
+ * @param oldName Old name.
+ * @param newName New name.
+ * @param compress Whether to compress the resulting save file (default) or not.
+ *
* @return true if no error occurred. false otherwise.
*/
virtual bool copySavefile(const String &oldName, const String &newName, bool compress = true);
/**
- * List available savegames matching a given pattern.
+ * List available save files matching a given pattern.
*
- * Our pattern format is based on DOS paterns, also known as "glob" in the
- * POSIX world. Please refer to the Common::matchString() function to learn
+ * The pattern format is based on DOS patterns, also known as "glob" in the
+ * POSIX world. Refer to the Common::matchString() function for information
* about the precise pattern format.
*
- * @param pattern Pattern to match. Wildcards like * or ? are available.
+ * @param pattern Pattern to match. Wildcards like * or ? are allowed.
* @return List of strings for all present file names.
- * @see Common::matchString()
+ * @sa Common::matchString()
*/
virtual StringArray listSavefiles(const String &pattern) = 0;
/**
- * Refreshes the save files list (because some new files could've been added)
- * and remembers the "locked" files list. These files could not be used
+ * Refresh the save files list (because some new files might have been added)
+ * and remember the "locked" files list. These files cannot be used
* for saving or loading because they are being synced by CloudManager.
*/
virtual void updateSavefilesList(StringArray &lockedFiles) = 0;
More information about the Scummvm-git-logs
mailing list