Lots more documentation.

src/Assert.hpp

@@ -1,3 +1,4 @@
+/** @file */
 #include <sstream>
 #include <stdexcept>
 #include <string.h>
@@ -5,7 +6,13 @@
 
 #define __FILENAME__ (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : __FILE__)
 
+/// \defgroup Asserts Asserts
+/// \brief Group of non-editable strings with faster hashing.
+
+
 #ifndef NO_ASSERT
+/// @brief Asserts an expression is true. Throws an exception if the assertion fails.
+/// @ingroup Asserts
 #define Assert(expr)                                                                                                   \
     if (!(expr)) {                                                                                                     \
         std::stringstream ss;                                                                                          \
@@ -13,9 +20,12 @@
         ss << #expr << "\"";                                                                                           \
         throw ArbUt::Exception(ss.str());                                                                              \
     }
+
+/// @brief Asserts an expression is true for a range. The value in the range can be retrieved using ``item``.
+/// @ingroup Asserts
 #define AssertForEach(iterator, assertion)                                                                             \
     {                                                                                                                  \
-        for (auto item : iterator)                                                                                     \
+        for (auto item : (iterator))                                                                                   \
             Assert(assertion)                                                                                          \
     }
 #else
@@ -24,5 +34,9 @@
 #define AssertForEach(iterator, assertion) ;
 #endif
 
-#define AssertNotNull(value) Assert(value != nullptr)
+/// @brief Asserts a pointer is not null.
+/// @ingroup Asserts
+#define AssertNotNull(value) Assert((value) != nullptr)
+/// @brief Asserts a range is not null.
+/// @ingroup Asserts
 #define AssertAllNotNull(iterator) AssertForEach(iterator, item != nullptr)

src/Memory/BorrowedPtr.hpp

@@ -80,6 +80,9 @@ namespace ArbUt {
 namespace std {
     /// @brief Helper class for allowing hashing of BorrowedPtr.
     template <class T> struct hash<ArbUt::BorrowedPtr<T>> {
+        /// @brief Returns a hash of for a borrowed Pointer. Effectively just the raw memory address.
+        /// @param k A borrowed pointer.
+        /// @return The hash of the borrowed pointer.
         std::size_t operator()(const ArbUt::BorrowedPtr<T>& k) const { return (size_t)k.GetRaw(); }
     };
 }

src/Memory/UniquePtrList.hpp

@@ -17,21 +17,34 @@ namespace ArbUt {
 
     public:
         inline UniquePtrList() noexcept : _vector() {}
+        /// @brief Initialises a UniquePtrList from a std::vector of raw pointers.
+        /// @param vec A std::vector of raw pointers.
         inline UniquePtrList(const std::vector<ValueT*>& vec) noexcept : _vector(vec) {}
+        /// @brief Initialises a UniquePtrList with a certain capacity reserved for use. This does not set immediate size.
+        /// @param capacity The desired capacity.
         explicit inline UniquePtrList(size_t capacity) : _vector() { _vector.reserve(capacity); }
+        /// @brief Initialises a UniquePtrList from a initialiser_list.
+        /// @param l A initialiser_list
         inline UniquePtrList(const std::initializer_list<ValueT*>& l) noexcept : _vector(l) {}
+        /// @brief Initialises a UniquePtrList from a raw pointer range.
+        /// @param begin The raw pointer to the start of the list.
+        /// @param end The raw pointer to the end of the list.
         inline UniquePtrList(ValueT* const* begin, ValueT* const* end) noexcept : _vector(begin, end) {}
 
         UniquePtrList(const UniquePtrList<ValueT>&) = delete;
         UniquePtrList<ValueT>& operator=(const UniquePtrList<ValueT>&) = delete;
         ~UniquePtrList() noexcept { Clear(); }
 
+        /// @brief Clears the UniquePtrList, and run the destructor on all containing pointers.
         inline void Clear() noexcept {
             for (auto& i : _vector) {
                 delete i;
             }
         }
 
+        /// @brief Borrow a pointer at a certain index.
+        /// @param index The index to retrieve.
+        /// @return A borrowed pointer reference to the containing raw pointer.
         inline BorrowedPtr<ValueT> At(size_t index) const {
 #ifndef NO_ASSERT
             if (index >= _vector.size()) {
@@ -42,21 +55,32 @@ namespace ArbUt {
 #endif
             return _vector[index];
         }
+        /// @brief Returns a raw pointer at an index, and releases ownership. Proper handling of the memory is assumed to be done by the taker.
+        /// @param index The index to get the pointer from.
+        /// @return A raw pointer.
         ValueT* TakeOwnership(size_t index) {
             auto p = _vector[index];
             _vector[index] = nullptr;
             return p;
         }
+        /// @brief Swaps two pointers at indices with each other.
+        /// @param indexA The first index to swap from.
+        /// @param indexB The second index to swap from
         void Swap(size_t indexA, size_t indexB) {
             auto temp = _vector[indexA];
             _vector[indexA] = _vector[indexB];
             _vector[indexB] = temp;
         }
+        /// @brief Sets a pointer to a certain index. If an item already existed at that index, it's destructor will be called.
+        /// @param index The index to set the pointer to.
+        /// @param ptr The pointer to store.
         void Set(size_t index, ValueT* ptr) {
             delete _vector[index];
             _vector[index] = ptr;
         }
 
+        /// @brief Removes a pointer at a certain index. It's destructor will be called.
+        /// @param index The index to remove.
         inline void Remove(size_t index) {
 #ifndef NO_ASSERT
             if (index >= _vector.size()) {
@@ -69,13 +93,16 @@ namespace ArbUt {
             _vector.erase(_vector.begin() + index);
         }
 
+        /// @brief Check whether a pointer is contained in the list.
+        /// @param value The value to check for.
+        /// @return True if the list contains the pointer, false otherwise.
         inline bool Contains(const BorrowedPtr<ValueT>& value) const noexcept {
             return std::find(_vector.begin(), _vector.end(), value) != _vector.end();
         }
 
-        /// Find the index of the first occurrence of a value in the list, return -1 if none is found.
-        /// \param value The value we want the index for.
-        /// \return The index of the first occurrence of the value in the list, or -1 if none is found.
+        /// @brief Find the index of the first occurrence of a value in the list, return -1 if none is found.
+        /// @param value The value we want the index for.
+        /// @return The index of the first occurrence of the value in the list, or -1 if none is found.
         inline size_t IndexOf(const BorrowedPtr<ValueT>& value) const noexcept {
             const auto& it = std::find(_vector.begin(), _vector.end(), value);
             if (it == _vector.end())
@@ -83,19 +110,36 @@ namespace ArbUt {
             return std::distance(_vector.begin(), it);
         }
 
+        /// @brief Append a pointer to the list.
+        /// @param value The pointer to push to the list.
         inline void Append(ValueT* value) { _vector.push_back(value); }
+        /// @brief Borrow a pointer at a certain index.
+        /// @param index The index to retrieve.
+        /// @return A borrowed pointer reference to the containing raw pointer.
         inline BorrowedPtr<ValueT> operator[](size_t index) const { return At(index); }
 
-        inline size_t Count() const noexcept { return _vector.size(); }
+        /// @brief Returns the number of pointers contained.
+        /// @return The number of pointers contained.
+        [[nodiscard]] inline size_t Count() const noexcept { return _vector.size(); }
 
+        /// @brief returns an iterator to the beginning of the specified bucket
         iterator begin() noexcept { return _vector.begin(); }
+        /// @brief returns an iterator to the beginning of the specified bucket
         iterator end() noexcept { return _vector.end(); }
+        /// @brief returns an iterator to the end of the specified bucket
         const_iterator begin() const noexcept { return _vector.begin(); }
+        /// @brief returns an iterator to the end of the specified bucket
         const_iterator end() const noexcept { return _vector.end(); }
 
+        /// @brief Return a raw pointer to the beginning of the list.
+        /// @return A raw array pointer to the beginning of the list.
         ValueT* const* RawData() const noexcept { return _vector.data(); }
 
+        /// @brief Returns a std::vector representation of the current list.
+        /// @return A std::vector representation of the current list.
         const std::vector<ValueT*>& GetStdList() const noexcept { return _vector; }
+        /// @brief Returns a std::vector representation of the current list.
+        /// @return A std::vector representation of the current list.
         std::vector<ValueT*>& GetStdList() noexcept { return _vector; }
     };
 }

src/String/StringView.hpp

@@ -47,19 +47,33 @@ namespace ArbUt {
         std::shared_ptr<__ConstStringCharHolder> _str = GetEmptyString();
 
     public:
+        /// @brief Instantiate a StringView using a C string.
+        /// @param str A null-terminated C string.
         StringView(const char* str) noexcept
             : BasicStringView(CalcLength(str), Hash(str)), _str(new __ConstStringCharHolder(str, CalcLength(str))) {}
+        /// @brief Instantiate a StringView using a C string, as well as it's length.
+        /// @param str A null-terminated C string.
+        /// @param length The length of the C string
         StringView(const char* str, size_t length) noexcept
             : BasicStringView(length, Hash(str)), _str(new __ConstStringCharHolder(str, length)) {}
         StringView() noexcept : BasicStringView(0, Hash("")) {}
 
         /* Copy operators */
+        /// @brief Copy operator
+        /// @param other Other StringView
         StringView(const StringView& other) noexcept : BasicStringView(other._length, other._hash), _str(other._str) {}
+        /// @brief Special constructor of stringview, specifically designed for use of conversion from StringViewLiteral to StringView.
+        /// @param other Other StringView
+        /// @param c A null-terminated C string.
+        /// @param length The length of the C string.
         StringView(const BasicStringView& other, const char* c, size_t length) noexcept
             : BasicStringView(length, other.GetHash()), _str(new __ConstStringCharHolder(c, length)) {}
 
+        /// @brief Assignment operator.
+        /// @param other Stringview to assign.
+        /// @return current stringview.
         StringView& operator=(const StringView& other) noexcept {
-            if (_str == other._str) {
+            if (this == &other || _str == other._str) {
                 return *this;
             }
             _str = other._str;
@@ -68,7 +82,11 @@ namespace ArbUt {
             return *this;
         }
 
+        /// @brief Returns null-terminated C string.
+        /// @return Null-terminated C string.
         [[nodiscard]] inline const char* c_str() const noexcept override { return _str->GetValue(); }
+        /// @brief Returns std string_view of internal C string.
+        /// @return std::string_view.
         [[nodiscard]] inline std::string_view std_str() const noexcept override { return _str->GetValue(); }
 
         inline constexpr bool operator==(const std::string_view& rhs) const noexcept override {
@@ -80,14 +98,23 @@ namespace ArbUt {
         inline constexpr bool operator==(const char* rhs) const noexcept override { return _hash == Hash(rhs); }
         inline constexpr bool operator!=(const char* rhs) const noexcept override { return _hash != Hash(rhs); }
 
+        /// @brief Calculates the hash for a given C string.
+        /// @param val A null-terminated C string.
+        /// @return A hash of the given string.
         [[maybe_unused]] [[nodiscard]] inline static constexpr uint32_t CalculateHash(const char* val) noexcept {
             return Hash(val);
         }
+
+        /// @brief Calculates the hash for a given std string.
+        /// @param val A std string.
+        /// @return A hash of the given string.
         [[maybe_unused]] [[nodiscard]] inline static constexpr uint32_t
         CalculateHash(const std::string_view& val) noexcept {
             return Hash(val.data());
         }
 
+        /// @brief Returns an empty string.
+        /// @return An empty string.
         static const StringView& EmptyString();
     };
 }
@@ -95,6 +122,9 @@ namespace ArbUt {
 namespace std {
     /// @brief Helper class for hashing string views.
     template <> struct hash<ArbUt::StringView> {
+        /// @brief Returns the hash of a stringview.
+        /// @param s a StringView.
+        /// @return The hash of the StringView.
         constexpr std::size_t operator()(ArbUt::StringView const& s) const noexcept { return s.GetHash(); }
     };
 }

src/String/StringViewLiteral.hpp

@@ -13,14 +13,24 @@ namespace ArbUt {
         const char* _str;
 
     public:
-        constexpr StringViewLiteral(const char* str, size_t size) noexcept
+        /// @brief Compile time initialisation of a StringViewLiteral.
+        /// @param str A null terminated C string.
+        /// @param size A The length of the string.
+        consteval StringViewLiteral(const char* str, size_t size) noexcept
             : BasicStringView(size, Hash(str)), _str(str) {}
-        constexpr StringViewLiteral(const char* str) noexcept : StringViewLiteral(str, CalcLength(str)){};
+        /// @brief Compile time initialisation of a StringViewLiteral. Length is calculated at compile.
+        /// @param str A null terminated C string.
+        consteval StringViewLiteral(const char* str) noexcept : StringViewLiteral(str, CalcLength(str)){};
         [[nodiscard]] inline constexpr const char* c_str() const noexcept override { return _str; }
         [[nodiscard]] constexpr std::string_view std_str() const noexcept override {
             return std::string_view(_str, _length);
         }
-        constexpr std::size_t operator()(StringViewLiteral const& s) const noexcept { return s.GetHash(); }
+        /// @brief Returns the hash of a s.tringview literal.
+        /// @param s A stringview literal.
+        /// @return The hash of the stringview literal.
+        consteval std::size_t operator()(StringViewLiteral const& s) const noexcept { return s.GetHash(); }
+        /// @brief Converts stringview literal into non-literal (for use during runtime).
+        /// @return A normal StringView.
         inline operator StringView() const noexcept { return StringView(*this, _str, _length); }
 
         inline constexpr bool operator==(const std::string_view& rhs) const noexcept override {
@@ -37,14 +47,17 @@ namespace ArbUt {
 namespace std {
     /// @brief Helper class for getting the hash of a string view literal.
     template <> struct hash<ArbUt::StringViewLiteral> {
-        constexpr std::size_t operator()(ArbUt::StringViewLiteral const& s) const noexcept { return s.GetHash(); }
+        /// @brief Returns the hash of a stringview.
+        /// @param s a StringView.
+        /// @return The hash of the StringView.
+        consteval std::size_t operator()(ArbUt::StringViewLiteral const& s) const noexcept { return s.GetHash(); }
     };
 }
 
-inline constexpr ArbUt::StringViewLiteral operator"" _const_nocase(const char* c, size_t l) {
+inline consteval ArbUt::StringViewLiteral operator"" _const_nocase(const char* c, size_t l) {
     return ArbUt::StringViewLiteral(c, l);
 }
-inline constexpr ArbUt::StringViewLiteral operator"" _cnc(const char* c, size_t l) {
+inline consteval ArbUt::StringViewLiteral operator"" _cnc(const char* c, size_t l) {
     return ArbUt::StringViewLiteral(c, l);
 }