diff --git a/common/achievements.h b/common/achievements.h index 0355374ed80..fcd74bcf3e7 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 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 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 { 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); + + /** @} */ + + /** + * @name Methods for manipulating individual statistics + * @{ + */ - // Methods to manipulate 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 5e669e7e119..205a9eb613a 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 @@ -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 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 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 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 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 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 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 @@ -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 @@ -155,6 +200,10 @@ Op for_each(In first, In last, Op f) { return f; } +/** + * @} + */ + template 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 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 void sort(T *first, T *last) { @@ -247,6 +310,10 @@ void sort(T first, T last) { sort(first, last, Less()); } +/** + * @} + */ + // 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 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 c7a0f731f75..a27a8ec121c 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, 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 191febf3c36..672837c7e57 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 SortedArray : public Array { @@ -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 775a83abaa6..64fc1846786 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 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 BitStream8MSB; @@ -481,6 +483,8 @@ typedef BitStreamImpl BitStreamMemory32 /** @} */ +/** @} */ + } // End of namespace Common #endif // COMMON_BITSTREAM_H