[Scummvm-git-logs] scummvm master -> b6c5d415eeb96a3b9b0bfa8f18b68ca67259c147
sev-
sev at scummvm.org
Mon Oct 5 11:43:55 UTC 2020
This automated email contains information about 2 new commits which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .
Summary:
59fce86705 DOXYGEN: updates in first header files
b6c5d415ee small edits, to be squashed
Commit: 59fce86705825d7695e9b76f8764a27cdf9481f5
https://github.com/scummvm/scummvm/commit/59fce86705825d7695e9b76f8764a27cdf9481f5
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-10-05T13:43:50+02:00
Commit Message:
DOXYGEN: updates in first header files
Add and improve doxygen blocks in header files:
- achievements.h
- algorithm.h
- archive.h
- array.h
- bitstream.h
Changed paths:
common/achievements.h
common/algorithm.h
common/archive.h
common/array.h
common/bitstream.h
diff --git a/common/achievements.h b/common/achievements.h
index 0355374ed8..fcd74bcf3e 100644
--- a/common/achievements.h
+++ b/common/achievements.h
@@ -51,58 +51,135 @@ enum AchievementsPlatform {
/**
- * Per-game achievements information structure item.
+ * Information structure for game-specific achievements.
*/
struct AchievementDescription {
- const char *id; // achievement internal id, e.g. "ACHIEVEMENT_TIMING"
- bool isHidden; // achievement is hidden
- const char *title; // achievement displayed text, e.g. "Marathon Runner"
- const char *comment; // optional achievement hint / comment, e.g. "Finish the game in less than 4 hours"
+ const char *id; //!< Achievement internal ID, such as "ACHIEVEMENT_TIMING".
+ bool isHidden; //!< Whether the achievement is hidden.
+ const char *title; //!< Achievement displayed text, such as "Marathon Runner".
+ const char *comment; //!< Optional achievement hint or comment, such as "Finish the game in less than 4 hours".
};
/**
- * Per-game achievements information structure item.
+ * Information structure for platform-specific achievements.
*/
struct AchievementsInfo {
- Common::AchievementsPlatform platform; // achievements platform, e.g. STEAM_ACHIEVEMENTS
- Common::String appId; // achievements application ID of given platform
- Common::Array<AchievementDescription> descriptions; // descriptions of all game achievements
+ Common::AchievementsPlatform platform; //!< Achievements platform, such as "STEAM_ACHIEVEMENTS".
+ Common::String appId; //!< Achievements application ID of the given platform.
+ Common::Array<AchievementDescription> descriptions; //!< Descriptions of all game achievements.
AchievementsInfo() {platform = Common::UNK_ACHIEVEMENTS;}
};
+/**
+ * Class for manipulating the achievements.
+ *
+ * Use the Achievements Manager class to edit the in-game achievements.
+ */
class AchievementsManager : public Singleton<AchievementsManager> {
public:
AchievementsManager();
~AchievementsManager();
-
+
+ /**
+ * Set a platform and application ID as active domain.
+ *
+ * @param[in] platform Achievements platform.
+ * @param[in] appId Achievements application ID of the given platform.
+ */
bool setActiveDomain(AchievementsPlatform platform, const String &appId);
- bool unsetActiveDomain();
- bool isReady() { return _iniFile != nullptr; }
+ bool unsetActiveDomain(); //!< Unset the current active domain.
+ bool isReady() { return _iniFile != nullptr; } //!< Check whether the domain is ready.
+
+ /**
+ * @name Methods for manipulating individual achievements
+ * @{
+ */
+
+ /** Set an achievement.
+ *
+ * @param[in] id Internal ID of the achievement.
+ * @param[in] displayedMessage Message displayed when the achievement is achieved.
+ */
- // Methods to manipulate individual achievements
bool setAchievement(const String &id, const String &displayedMessage);
+
+ /**
+ * Set an achievement as achieved.
+ *
+ * @param[in] id Internal ID of the achievement.
+ */
+
bool isAchieved(const String &id);
+
+ /**
+ * Clear an achieved achievement.
+ *
+ * @param[in] id Internal ID of the achievement.
+ */
+
bool clearAchievement(const String &id);
-
- // Methods to manipulate individual statistics
+
+ /** @} */
+
+ /**
+ * @name Methods for manipulating individual statistics
+ * @{
+ */
+
+ /**
+ * Get a statistic (integer).
+ *
+ * @param[in] id Internal ID of the achievement.
+ */
+
int getStatInt(const String &id);
+
+ /**
+ * Set a statistic to an integer number.
+ *
+ * @param[in] id Internal ID of the achievement.
+ * @param[in] value Value to which the statistic is set.
+ */
+
bool setStatInt(const String &id, int value);
+
+ /**
+ * Get a statistic (float).
+ *
+ * @param[in] id Internal ID of the achievement.
+ */
+
float getStatFloat(const String &id);
+
+ /**
+ * Set a statistic to a float number.
+ *
+ * @param[in] id Internal ID of the achievement.
+ * @param[in] value Value to which the statistic is set.
+ */
+
bool setStatFloat(const String &id, float value);
- // Methods to reset everything
- bool resetAllAchievements();
- bool resetAllStats();
+ /** @} */
+
+ /**
+ * @name Methods for resetting achievements and statistics
+ * @{
+ */
+ bool resetAllAchievements(); //!< Reset all achievements.
+ bool resetAllStats(); //!< Reset all statistics.
+
+ /** @} */
private:
INIFile *_iniFile;
String _iniFileName;
};
-/** Shortcut for accessing the achievements manager. */
+/** Shortcut for accessing the Achievements Manager. */
#define AchMan Common::AchievementsManager::instance()
/** @} */
diff --git a/common/algorithm.h b/common/algorithm.h
index 5e669e7e11..205a9eb613 100644
--- a/common/algorithm.h
+++ b/common/algorithm.h
@@ -39,8 +39,14 @@ namespace Common {
*/
/**
- * Copies data from the range [first, last) to [dst, dst + (last - first)).
- * It requires the range [dst, dst + (last - first)) to be valid.
+ * @name Copy templates
+ * @{
+ */
+
+/**
+ * Copy data from the range [first, last) to [dst, dst + (last - first)).
+ *
+ * The function requires the range [dst, dst + (last - first)) to be valid.
* It also requires dst not to be in the range [first, last).
*/
template<class In, class Out>
@@ -51,11 +57,12 @@ Out copy(In first, In last, Out dst) {
}
/**
- * Copies data from the range [first, last) to [dst - (last - first), dst).
- * It requires the range [dst - (last - first), dst) to be valid.
+ * Copy data from the range [first, last) to [dst - (last - first), dst).
+ *
+ * The function requires the range [dst - (last - first), dst) to be valid.
* It also requires dst not to be in the range [first, last).
*
- * Unlike copy copy_backward copies the data from the end to the beginning.
+ * Unlike copy, copy_backward copies the data from the end to the beginning.
*/
template<class In, class Out>
Out copy_backward(In first, In last, Out dst) {
@@ -65,11 +72,12 @@ Out copy_backward(In first, In last, Out dst) {
}
/**
- * Copies data from the range [first, last) to [dst, dst + (last - first)).
- * It requires the range [dst, dst + (last - first)) to be valid.
+ * Copy data from the range [first, last) to [dst, dst + (last - first)).
+ *
+ * The function requires the range [dst, dst + (last - first)) to be valid.
* It also requires dst not to be in the range [first, last).
*
- * Unlike copy or copy_backward it does not copy all data. It only copies
+ * Unlike copy or copy_backward, it does not copy all data. It only copies
* a data element when operator() of the op parameter returns true for the
* passed data element.
*/
@@ -83,23 +91,51 @@ Out copy_if(In first, In last, Out dst, Op op) {
return dst;
}
-// Our 'specialized' 'fill' template for char, signed char and unsigned char arrays.
-// Since C++ doesn't support partial specialized template functions (currently) we
-// are going this way...
-// With this we assure the usage of memset for those, which should be
-// faster than a simple loop like for the generic 'fill'.
+/**
+ * @}
+ */
+
+/**
+ * @name Fill templates
+ * @{
+ */
+
+/**
+ * A 'fill' template for signed char arrays.
+ *
+ * Since C++ does not currently support partial specialized template functions,
+ * this solution is implemented.
+ * With this template, the usage of memset is assured, which is
+ * faster than a simple loop like for the generic 'fill'.
+ */
template<class Value>
signed char *fill(signed char *first, signed char *last, Value val) {
memset(first, (val & 0xFF), last - first);
return last;
}
+/**
+ * A 'fill' template for unsigned char arrays.
+ *
+ * Since C++ does not currently support partial specialized template functions,
+ * this solution is implemented.
+ * With this template, the usage of memset is assured, which is
+ * faster than a simple loop like for the generic 'fill'.
+ */
template<class Value>
unsigned char *fill(unsigned char *first, unsigned char *last, Value val) {
memset(first, (val & 0xFF), last - first);
return last;
}
+/**
+ * A 'fill' template for char arrays.
+ *
+ * Since C++ does not currently support partial specialized template functions,
+ * this solution is implemented.
+ * With this template, the usage of memset is assured, which is
+ * faster than a simple loop like for the generic 'fill'.
+ */
template<class Value>
char *fill(char *first, char *last, Value val) {
memset(first, (val & 0xFF), last - first);
@@ -107,7 +143,16 @@ char *fill(char *first, char *last, Value val) {
}
/**
- * Sets all elements in the range [first, last) to val.
+ * @}
+ */
+
+/**
+ * @name Range templates
+ * @{
+ */
+
+/**
+ * Set all elements in the range [first, last) to val.
*/
template<class In, class Value>
In fill(In first, In last, const Value &val) {
@@ -117,8 +162,8 @@ In fill(In first, In last, const Value &val) {
}
/**
- * Finds the first data value in the range [first, last) matching v.
- * For data comperance it uses operator == of the data elements.
+ * Find the first data value in the range [first, last) matching v.
+ * For data comparison, it uses operator == of the data elements.
*/
template<class In, class T>
In find(In first, In last, const T &v) {
@@ -131,7 +176,7 @@ In find(In first, In last, const T &v) {
}
/**
- * Finds the first data value in the range [first, last) for which
+ * Find the first data value in the range [first, last), for which
* the specified predicate p returns true.
*/
template<class In, class Pred>
@@ -145,7 +190,7 @@ In find_if(In first, In last, Pred p) {
}
/**
- * Applies the function f on all elements of the range [first, last).
+ * Apply the function f on all elements from the range [first, last).
* The processing order is from beginning to end.
*/
template<class In, class Op>
@@ -155,6 +200,10 @@ Op for_each(In first, In last, Op f) {
return f;
}
+/**
+ * @}
+ */
+
template<typename T>
unsigned int distance(T *first, T *last) {
return last - first;
@@ -205,12 +254,18 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
}
/**
- * Simple sort function, modeled after std::sort.
- * It compares data with the given comparator object comp.
+ * @name Sorting templates
+ * @{
+ */
+
+/**
+ * Simple sorting function, modeled after std::sort.
*
- * Like std::sort this is not guaranteed to be stable.
+ * This function compares data with the given comparator object comp.
*
- * Two small quotes from wikipedia about stability:
+ * Like std::sort, this is not guaranteed to be stable.
+ *
+ * Two quotes from Wikipedia about stability:
*
* Stable sorting algorithms maintain the relative order of records with
* equal keys.
@@ -218,11 +273,16 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
* Unstable sorting algorithms may change the relative order of records with
* equal keys, but stable sorting algorithms never do so.
*
- * For more information on that topic check out:
+ * For more information, see:
* http://en.wikipedia.org/wiki/Sorting_algorithm#Stability
*
- * NOTE: Actually as the time of writing our implementation is unstable.
+ * @note Currently, this implementation is unstable.
+ *
+ * @param[in] first First element to sort.
+ * @param[in] last Last element to sort.
+ * @param[in] comp Comparator object.
*/
+
template<typename T, class StrictWeakOrdering>
void sort(T first, T last, StrictWeakOrdering comp) {
if (first == last)
@@ -235,7 +295,10 @@ void sort(T first, T last, StrictWeakOrdering comp) {
}
/**
- * Simple sort function, modeled after std::sort.
+ * Simple sorting function, modeled after std::sort.
+ *
+ * @param[in] first First element to sort.
+ * @param[in] last Last element to sort.
*/
template<typename T>
void sort(T *first, T *last) {
@@ -247,6 +310,10 @@ void sort(T first, T last) {
sort(first, last, Less<typename T::ValueType>());
}
+/**
+ * @}
+ */
+
// MSVC is complaining about the minus operator being applied to an unsigned type
// We disable this warning for the affected section of code
#if defined(_MSC_VER)
@@ -255,7 +322,7 @@ void sort(T first, T last) {
#endif
/**
- * Euclid's algorithm to compute the greatest common divisor.
+ * Euclidean algorithm to compute the greatest common divisor.
*/
template<class T>
T gcd(T a, T b) {
@@ -301,10 +368,10 @@ T nextHigher2(T v) {
*
* Replaces all occurrences of "original" in [begin, end) with occurrences of "replaced".
*
- * @param[in, out] begin: First element to be examined.
- * @param[in] end: Last element in the seubsection. Not examined.
- * @param[in] original: Elements to be replaced.
- * @param[in] replaced: Element to replace occurrences of "original".
+ * @param[in,out] begin First element to be examined.
+ * @param[in] end Last element in the subsection. Not examined.
+ * @param[in] original Elements to be replaced.
+ * @param[in] replaced Element to replace occurrences of @p original.
*
* @note Usage examples and unit tests may be found in "test/common/algorithm.h"
*/
@@ -319,7 +386,6 @@ void replace(It begin, It end, const Dat &original, const Dat &replaced) {
/** @} */
-
} // End of namespace Common
#endif
diff --git a/common/archive.h b/common/archive.h
index c7a0f731f7..a27a8ec121 100644
--- a/common/archive.h
+++ b/common/archive.h
@@ -34,25 +34,23 @@ namespace Common {
* @defgroup common_arch Archive
* @ingroup common
*
- * @brief The Archive module allows managing the member of arbitrary containers in a uniform
+ * @brief The Archive module allows for managing the members of arbitrary containers in a uniform
* fashion.
- * It also supports looking up by names and file names, opening a file, and returning usable input stream.
- *
+ * It also supports looking up by names and file names, opening a file, and returning a usable input stream.
* @{
*/
-
class FSNode;
class SeekableReadStream;
/**
- * ArchiveMember is an abstract interface to represent elements inside
- * implementations of Archive.
+ * The ArchiveMember class is an abstract interface to represent elements inside
+ * implementations of an archive.
*
* Archive subclasses must provide their own implementation of ArchiveMember,
- * and use it when serving calls to listMembers() and listMatchingMembers().
- * Alternatively, the GenericArchiveMember below can be used.
+ * and use it when serving calls to @ref Archive::listMembers and @ref Archive::listMatchingMembers.
+ * Alternatively, you can use the @ref GenericArchiveMember.
*/
class ArchiveMember {
public:
@@ -93,9 +91,9 @@ public:
/**
- * Archive allows managing of member of arbitrary containers in a uniform
- * fashion, allowing lookup by (file)names.
- * It also supports opening a file and returning an usable input stream.
+ * The Archive class allows for managing the members of arbitrary containers in a uniform
+ * fashion, allowing lookup by (file) names.
+ * It also supports opening a file and returning a usable input stream.
*/
class Archive {
public:
@@ -109,40 +107,42 @@ public:
virtual bool hasFile(const String &name) const = 0;
/**
- * Add all members of the Archive matching the specified pattern to list.
+ * Add all members of the Archive matching the specified pattern to the list.
* Must only append to list, and not remove elements from it.
*
- * @return the number of members added to list
+ * @return The number of members added to list.
*/
virtual int listMatchingMembers(ArchiveMemberList &list, const String &pattern) const;
/**
- * Add all members of the Archive to list.
+ * Add all members of the Archive to the list.
* Must only append to list, and not remove elements from it.
*
- * @return the number of names added to list
+ * @return The number of names added to list.
*/
virtual int listMembers(ArchiveMemberList &list) const = 0;
/**
- * Returns a ArchiveMember representation of the given file.
+ * Return an ArchiveMember representation of the given file.
*/
virtual const ArchiveMemberPtr getMember(const String &name) const = 0;
/**
* Create a stream bound to a member with the specified name in the
* archive. If no member with this name exists, 0 is returned.
- * @return the newly created input stream
+ *
+ * @return The newly created input stream.
*/
virtual SeekableReadStream *createReadStreamForMember(const String &name) const = 0;
};
/**
- * SearchSet enables access to a group of Archives through the Archive interface.
+ * The SearchSet class enables access to a group of Archives through the Archive interface.
+ *
* Its intended usage is a situation in which there are no name clashes among names in the
* contained Archives, hence the simplistic policy of always looking for the first
- * match. SearchSet *DOES* guarantee that searches are performed in *DESCENDING*
+ * match. SearchSet does guarantee that searches are performed in DESCENDING
* priority order. In case of conflicting priorities, insertion order prevails.
*/
class SearchSet : public Archive {
@@ -161,8 +161,7 @@ class SearchSet : public Archive {
ArchiveNodeList::iterator find(const String &name);
ArchiveNodeList::const_iterator find(const String &name) const;
- // Add an archive keeping the list sorted by descending priority.
- void insert(const Node& node);
+ void insert(const Node& node); //!< Add an archive keeping the list sorted by descending priority.
bool _ignoreClashes;
@@ -176,58 +175,56 @@ public:
void add(const String& name, Archive *arch, int priority = 0, bool autoFree = true);
/**
- * Create and add a FSDirectory by name
+ * Create and add a 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 a FSDirectory by FSNode.
*/
void addDirectory(const String &name, const FSNode &directory, int priority = 0, int depth = 1, bool flat = false);
/**
- * Create and add a sub directory by name (caseless).
+ * Create and add a subdirectory by name (caseless).
*
- * It is also possible to add sub directories of sub directories (of any depth) with this function.
- * The path seperator for this case is SLASH for *all* systems.
+ * It is also possible to add subdirectories of subdirectories (of any depth) with this function.
+ * The path seperator for this case is SLASH for all systems.
*
- * An example would be:
+ * Example:
*
* "game/itedata"
*
- * In this example the code would first try to search for all directories matching
+ * In this example, the code first tries to search for all directories matching
* "game" (case insensitive) in the path "directory" first and search through all
* of the matches for "itedata" (case insensitive too).
*
- * Note that it will add *all* matches found!
+ * Note that it will add all matches found!
*
- * Even though this method is currently implemented via addSubDirectoriesMatching it is not safe
+ * Even though this method is currently implemented via addSubDirectoriesMatching, it is not safe
* to assume that this method is using anything other than a simple case insensitive compare.
- * Thus do not use any tokens like '*' or '?' in the "caselessName" parameter of this function!
+ * Thus, do not use any tokens like '*' or '?' in the "caselessName" parameter of this function.
*/
void addSubDirectoryMatching(const FSNode &directory, const String &caselessName, int priority = 0, int depth = 1, bool flat = false) {
addSubDirectoriesMatching(directory, caselessName, true, priority, depth, flat);
}
/**
- * Create and add sub directories by pattern.
+ * Create and add subdirectories by pattern.
*
- * It is also possible to add sub directories of sub directories (of any depth) with this function.
- * The path seperator for this case is SLASH for *all* systems.
+ * It is also possible to add subdirectories of subdirectories (of any depth) with this function.
+ * The path seperator for this case is SLASH for all systems.
*
- * An example would be:
+ * Example:
*
* "game/itedata"
*
- * In this example the code would first try to search for all directories matching
+ * In this example, the code first tries to search for all directories matching
* "game" in the path "directory" first and search through all of the matches for
- * "itedata". If "ingoreCase" is set to true, the code would do a case insensitive
+ * "itedata". If "ingoreCase" is set to true, the code does a case insensitive
* match, otherwise it is doing a case sensitive match.
*
- * This method works of course also with tokens. For a list of available tokens
- * see the documentation for Common::matchString.
- *
- * @see Common::matchString
+ * This method also works with tokens. For a list of available tokens,
+ * see @ref Common::matchString.
*/
void addSubDirectoriesMatching(const FSNode &directory, String origPattern, bool ignoreCase, int priority = 0, int depth = 1, bool flat = false);
@@ -242,7 +239,7 @@ public:
bool hasArchive(const String &name) const;
/**
- * Empties the searchable set.
+ * Empty the searchable set.
*/
virtual void clear();
@@ -258,14 +255,14 @@ public:
virtual const ArchiveMemberPtr getMember(const String &name) const;
/**
- * Implements createReadStreamForMember from Archive base class. The current policy is
+ * Implement createReadStreamForMember from the Archive base class. The current policy is
* opening the first file encountered that matches the name.
*/
virtual SeekableReadStream *createReadStreamForMember(const String &name) const;
/**
- * Ignore clashes when adding directories. For more details see the corresponding parameter
- * in FSDirectory documentation
+ * Ignore clashes when adding directories. For more details, see the corresponding parameter
+ * in FSDirectory documentation.
*/
void setIgnoreClashes(bool ignoreClashes) { _ignoreClashes = ignoreClashes; }
};
@@ -275,7 +272,7 @@ class SearchManager : public Singleton<SearchManager>, public SearchSet {
public:
/**
- * Resets the search manager to the default list of search paths (system
+ * Reset the Search Manager to the default list of search paths (system
* specific dirs + current dir).
*/
virtual void clear();
@@ -285,7 +282,7 @@ private:
SearchManager();
};
-/** Shortcut for accessing the search manager. */
+/** Shortcut for accessing the Search Manager. */
#define SearchMan Common::SearchManager::instance()
/** @} */
diff --git a/common/array.h b/common/array.h
index 191febf3c3..672837c7e5 100644
--- a/common/array.h
+++ b/common/array.h
@@ -38,17 +38,15 @@ namespace Common {
* @defgroup common_array Arrays
* @ingroup common
*
- * @brief Functions for working on arrays.
- *
+ * @brief Functions for replacing std arrays.
* @{
*/
-
/**
* This class implements a dynamically sized container, which
- * can be accessed similar to a regular C++ array. Accessing
+ * can be accessed similarly to a regular C++ array. Accessing
* elements is performed in constant time (like with plain arrays).
- * In addition, one can append, insert and remove entries (this
+ * In addition, you can append, insert, and remove entries (this
* is the 'dynamic' part). Doing that in general takes time
* proportional to the number of elements in the array.
*
@@ -74,7 +72,7 @@ public:
Array() : _capacity(0), _size(0), _storage(nullptr) {}
/**
- * Constructs an array with `count` default-inserted instances of T. No
+ * Construct an array with `count` default-inserted instances of @p T. No
* copies are made.
*/
explicit Array(size_type count) : _size(count) {
@@ -84,7 +82,7 @@ public:
}
/**
- * Constructs an array with `count` copies of elements with value `value`.
+ * Construct an array with `count` copies of elements with value `value`.
*/
Array(size_type count, const T &value) : _size(count) {
allocCapacity(count);
@@ -134,7 +132,7 @@ public:
_capacity = _size = 0;
}
- /** Appends element to the end of the array. */
+ /** Append an element to the end of the array. */
void push_back(const T &element) {
if (_size + 1 <= _capacity)
new ((void *)&_storage[_size++]) T(element);
@@ -150,7 +148,7 @@ public:
insert_aux(end(), array.begin(), array.end());
}
- /** Removes the last element of the array. */
+ /** Remove the last element of the array. */
void pop_back() {
assert(_size > 0);
_size--;
@@ -158,35 +156,35 @@ public:
_storage[_size].~T();
}
- /** Returns a pointer to the underlying memory serving as element storage. */
+ /** Return a pointer to the underlying memory serving as element storage. */
const T *data() const {
return _storage;
}
- /** Returns a pointer to the underlying memory serving as element storage. */
+ /** Return a pointer to the underlying memory serving as element storage. */
T *data() {
return _storage;
}
- /** Returns a reference to the first element of the array. */
+ /** Return a reference to the first element of the array. */
T &front() {
assert(_size > 0);
return _storage[0];
}
- /** Returns a reference to the first element of the array. */
+ /** Return a reference to the first element of the array. */
const T &front() const {
assert(_size > 0);
return _storage[0];
}
- /** Returns a reference to the last element of the array. */
+ /** Return a reference to the last element of the array. */
T &back() {
assert(_size > 0);
return _storage[_size-1];
}
- /** Returns a reference to the last element of the array. */
+ /** Return a reference to the last element of the array. */
const T &back() const {
assert(_size > 0);
return _storage[_size-1];
@@ -204,7 +202,7 @@ public:
}
/**
- * Inserts element before pos.
+ * Insert an element before @p pos.
*/
void insert(iterator pos, const T &element) {
insert_aux(pos, &element, &element + 1);
@@ -377,7 +375,7 @@ protected:
* Unlike std::vector::insert, this method does not accept
* arbitrary iterators, mainly because our iterator system is
* seriously limited and does not distinguish between input iterators,
- * output iterators, forward iterators or random access iterators.
+ * output iterators, forward iterators, or random access iterators.
*
* So, we simply restrict to Array iterators. Extending this to arbitrary
* random access iterators would be trivial.
@@ -404,7 +402,7 @@ protected:
uninitialized_copy(oldStorage, oldStorage + idx, _storage);
// Copy the data we insert
uninitialized_copy(first, last, _storage + idx);
- // Afterwards copy the old data from the position where we
+ // Afterwards, copy the old data from the position where we
// insert.
uninitialized_copy(oldStorage + idx, oldStorage + _size, _storage + idx + n);
@@ -442,7 +440,7 @@ protected:
};
/**
- * Double linked list with sorted nodes.
+ * Doubly linked list with sorted nodes.
*/
template<class T, typename CompareArgType = const void *>
class SortedArray : public Array<T> {
@@ -456,7 +454,7 @@ public:
}
/**
- * Inserts element at the sorted position.
+ * Insert an element at the sorted position.
*/
void insert(const T &element) {
if (!this->_size) {
diff --git a/common/bitstream.h b/common/bitstream.h
index 775a83abaa..64fc184678 100644
--- a/common/bitstream.h
+++ b/common/bitstream.h
@@ -49,19 +49,19 @@ namespace Common {
* gives access to their bits, one at a time.
*
* For example, a bit stream with the layout parameters 32, true, false
- * for valueBits, isLE and isMSB2LSB, reads 32bit little-endian values
+ * for valueBits, isLE and isMSB2LSB, reads 32-bit little-endian values
* from the data stream and hands out the bits in the order of LSB to MSB.
*/
template<class STREAM, int valueBits, bool isLE, bool MSB2LSB>
class BitStreamImpl {
private:
- STREAM *_stream; ///< The input stream.
- DisposeAfterUse::Flag _disposeAfterUse; ///< Should we delete the stream on destruction?
+ STREAM *_stream; //!< The input stream.
+ DisposeAfterUse::Flag _disposeAfterUse; //!< Whether to delete the stream on destruction.
- uint64 _bitContainer; ///< The currently available bits.
- uint8 _bitsLeft; ///< Number of bits currently left in the bit container.
- uint32 _size; ///< Total bitstream size (in bits)
- uint32 _pos; ///< Current bitstream position (in bits)
+ uint64 _bitContainer; //!< The currently available bits.
+ uint8 _bitsLeft; //!< Number of bits currently left in the bit container.
+ uint32 _size; //!< Total bit stream size (in bits).
+ uint32 _pos; //!< Current bit stream position (in bits).
/** Read a data value. */
inline uint32 readData() {
@@ -85,7 +85,7 @@ private:
return 0;
}
- /** Fill the container with at least min bits. */
+ /** Fill the container with at least @p min bits. */
inline void fillContainer(size_t min) {
while (_bitsLeft < min) {
@@ -93,11 +93,11 @@ private:
if (_pos + _bitsLeft + valueBits <= _size) {
data = readData();
} else {
- // Peeking data out of bounds is well defined and returns 0 bits.
+ // Peeking data out of bounds is well-defined and returns 0 bits.
// This is for convenience when using speed-up techniques reading
- // more bits than actually available. Users should call eos() to
- // check if data was actually read out of bounds. Peeking out of
- // bounds does not set the eos flag.
+ // more bits than actually available. Call eos() to check if data
+ // was actually read out of bounds. Peeking out of bounds does not
+ // set the eos flag.
data = 0;
}
@@ -111,7 +111,7 @@ private:
}
}
- /** Get n bits from the bit container. */
+ /** Get @p n bits from the bit container. */
inline static uint32 getNBits(uint64 value, size_t n) {
if (n == 0)
return 0;
@@ -183,7 +183,7 @@ public:
/**
* Read a multi-bit value from the bit stream, without changing the stream's position.
*
- * The bit order is the same as in getBits().
+ * The bit order is the same as in @ref getBits().
*/
uint32 peekBits(size_t n) {
if (n > 32)
@@ -196,12 +196,12 @@ public:
/**
* Read a multi-bit value from the bit stream.
*
- * The value is read as if just taken as a whole from the bitstream.
+ * The value is read as if just taken as a whole from the bit stream.
*
* For example:
- * Reading a 4-bit value from an 8-bit bitstream with the contents 01010011:
- * If the bitstream is MSB2LSB, the 4-bit value would be 0101.
- * If the bitstream is LSB2MSB, the 4-bit value would be 0011.
+ * Reading a 4-bit value from an 8-bit bit stream with the contents 01010011:
+ * If the bit stream is MSB2LSB, the 4-bit value would be 0101.
+ * If the bit stream is LSB2MSB, the 4-bit value would be 0011.
*/
uint32 getBits(size_t n) {
if (n > 32)
@@ -218,12 +218,12 @@ public:
* Add a bit to the value x, making it an n+1-bit value.
*
* The current value is shifted and the bit is added to the
- * appropriate place, dependant on the stream's bitorder.
+ * appropriate place, depending on the stream's bit order.
*
* For example:
* A bit y is added to the value 00001100 with size 4.
- * If the stream's bitorder is MSB2LSB, the resulting value is 0001100y.
- * If the stream's bitorder is LSB2MSB, the resulting value is 000y1100.
+ * If the stream's bit order is MSB2LSB, the resulting value is 0001100y.
+ * If the stream's bit order is LSB2MSB, the resulting value is 000y1100.
*/
void addBit(uint32 &x, uint32 n) {
if (n >= 32)
@@ -244,7 +244,7 @@ public:
_pos = 0;
}
- /** Skip the specified amount of bits. */
+ /** Skip the specified number of bits. */
void skip(uint32 n) {
while (n > 32) {
fillContainer(32);
@@ -428,8 +428,10 @@ public:
};
-
-// typedefs for various memory layouts.
+/**
+ * @name Typedefs for various memory layouts
+ * @{
+ */
/** 8-bit data, MSB to LSB. */
typedef BitStreamImpl<SeekableReadStream, 8, false, true > BitStream8MSB;
@@ -481,6 +483,8 @@ typedef BitStreamImpl<BitStreamMemoryStream, 32, false, false> BitStreamMemory32
/** @} */
+/** @} */
+
} // End of namespace Common
#endif // COMMON_BITSTREAM_H
Commit: b6c5d415eeb96a3b9b0bfa8f18b68ca67259c147
https://github.com/scummvm/scummvm/commit/b6c5d415eeb96a3b9b0bfa8f18b68ca67259c147
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-10-05T13:43:50+02:00
Commit Message:
small edits, to be squashed
Changed paths:
common/algorithm.h
common/archive.h
common/array.h
common/bitstream.h
diff --git a/common/algorithm.h b/common/algorithm.h
index 205a9eb613..96a5c69056 100644
--- a/common/algorithm.h
+++ b/common/algorithm.h
@@ -305,6 +305,13 @@ void sort(T *first, T *last) {
sort(first, last, Less<T>());
}
+/**
+ * Simple sorting function, modeled after std::sort.
+ *
+ * @param[in] first First element to sort.
+ * @param[in] last Last element to sort.
+ */
+
template<class T>
void sort(T first, T last) {
sort(first, last, Less<typename T::ValueType>());
diff --git a/common/archive.h b/common/archive.h
index a27a8ec121..6387753a16 100644
--- a/common/archive.h
+++ b/common/archive.h
@@ -55,9 +55,9 @@ class SeekableReadStream;
class ArchiveMember {
public:
virtual ~ArchiveMember() { }
- virtual SeekableReadStream *createReadStream() const = 0;
- virtual String getName() const = 0;
- virtual String getDisplayName() const { return getName(); }
+ 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. */
};
typedef SharedPtr<ArchiveMember> ArchiveMemberPtr;
@@ -84,8 +84,8 @@ class GenericArchiveMember : public ArchiveMember {
const Archive *_parent;
const String _name;
public:
- GenericArchiveMember(const String &name, const Archive *parent);
- String getName() const;
+ GenericArchiveMember(const String &name, const Archive *parent); /*!< Create a generic archive member. */
+ String getName() const; /*!< Get the name of a generic archive member. */
SeekableReadStream *createReadStream() const;
};
diff --git a/common/array.h b/common/array.h
index 672837c7e5..792ebd856c 100644
--- a/common/array.h
+++ b/common/array.h
@@ -140,6 +140,7 @@ public:
insert_aux(end(), &element, &element + 1);
}
+ /** Append an element to the end of the array. */
void push_back(const Array<T> &array) {
if (_size + array.size() <= _capacity) {
uninitialized_copy(array.begin(), array.end(), end());
diff --git a/common/bitstream.h b/common/bitstream.h
index 64fc184678..9a30dfb4cb 100644
--- a/common/bitstream.h
+++ b/common/bitstream.h
@@ -302,7 +302,7 @@ private:
uint32 _pos;
DisposeAfterUse::Flag _disposeMemory;
bool _eos;
-
+/** @overload */
public:
BitStreamMemoryStream(const byte *dataPtr, uint32 dataSize, DisposeAfterUse::Flag disposeMemory = DisposeAfterUse::NO) :
_ptrOrig(dataPtr),
More information about the Scummvm-git-logs
mailing list