[tint] Fix a load of doxygen warnings
Something I changed made it wake up.
Change-Id: I2dd6c289d0a7eba00a7f81852b873e4dfd41d542
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/143382
Commit-Queue: Ben Clayton <bclayton@google.com>
Reviewed-by: James Price <jrprice@google.com>
Kokoro: Kokoro <noreply+kokoro@google.com>
Auto-Submit: Ben Clayton <bclayton@google.com>
diff --git a/src/tint/lang/core/builtin/number.h b/src/tint/lang/core/builtin/number.h
index 0ab6532..3bf71b0 100644
--- a/src/tint/lang/core/builtin/number.h
+++ b/src/tint/lang/core/builtin/number.h
@@ -327,6 +327,7 @@
StringStream& operator<<(StringStream& out, ConversionFailure failure);
/// Converts a number from one type to another, checking that the value fits in the target type.
+/// @param num the value to convert
/// @returns the resulting value of the conversion, or a failure reason.
template <typename TO, typename FROM>
tint::Result<TO, ConversionFailure> CheckedConvert(Number<FROM> num) {
@@ -419,9 +420,12 @@
#endif
#endif
-// https://gcc.gnu.org/bugzilla/show_bug.cgi?id=80635
+/// Disables the false-positive maybe-uninitialized compiler warnings
+/// @see https://gcc.gnu.org/bugzilla/show_bug.cgi?id=80635
TINT_BEGIN_DISABLE_WARNING(MAYBE_UNINITIALIZED);
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a + b, or an empty optional if the resulting value overflowed the AInt
inline std::optional<AInt> CheckedAdd(AInt a, AInt b) {
int64_t result;
@@ -444,6 +448,8 @@
return AInt(result);
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a + b, or an empty optional if the resulting value overflowed the float value
template <typename FloatingPointT,
typename = tint::traits::EnableIf<IsFloatingPoint<FloatingPointT>>>
@@ -455,6 +461,8 @@
return result;
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a - b, or an empty optional if the resulting value overflowed the AInt
inline std::optional<AInt> CheckedSub(AInt a, AInt b) {
int64_t result;
@@ -477,6 +485,8 @@
return AInt(result);
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a + b, or an empty optional if the resulting value overflowed the float value
template <typename FloatingPointT,
typename = tint::traits::EnableIf<IsFloatingPoint<FloatingPointT>>>
@@ -488,6 +498,8 @@
return result;
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a * b, or an empty optional if the resulting value overflowed the AInt
inline std::optional<AInt> CheckedMul(AInt a, AInt b) {
int64_t result;
@@ -522,6 +534,8 @@
return AInt(result);
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a * b, or an empty optional if the resulting value overflowed the float value
template <typename FloatingPointT,
typename = tint::traits::EnableIf<IsFloatingPoint<FloatingPointT>>>
@@ -533,6 +547,8 @@
return result;
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a / b, or an empty optional if the resulting value overflowed the AInt
inline std::optional<AInt> CheckedDiv(AInt a, AInt b) {
if (b == 0) {
@@ -546,6 +562,8 @@
return AInt{a.value / b.value};
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns a / b, or an empty optional if the resulting value overflowed the float value
template <typename FloatingPointT,
typename = tint::traits::EnableIf<IsFloatingPoint<FloatingPointT>>>
@@ -561,6 +579,8 @@
}
namespace detail {
+/// @param e1 the LHS number
+/// @param e2 the RHS number
/// @returns the remainder of e1 / e2
template <typename T>
inline T Mod(T e1, T e2) {
@@ -573,6 +593,8 @@
}
} // namespace detail
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns the remainder of a / b, or an empty optional if the resulting value overflowed the AInt
inline std::optional<AInt> CheckedMod(AInt a, AInt b) {
if (b == 0) {
@@ -586,6 +608,8 @@
return AInt{tint::detail::Mod(a.value, b.value)};
}
+/// @param a the LHS number
+/// @param b the RHS number
/// @returns the remainder of a / b, or an empty optional if the resulting value overflowed the
/// float value
template <typename FloatingPointT,
@@ -601,6 +625,9 @@
return result;
}
+/// @param a the LHS number of the multiply
+/// @param b the RHS number of the multiply
+/// @param c the RHS number of the addition
/// @returns a * b + c, or an empty optional if the value overflowed the AInt
inline std::optional<AInt> CheckedMadd(AInt a, AInt b, AInt c) {
if (auto mul = CheckedMul(a, b)) {
@@ -609,6 +636,8 @@
return {};
}
+/// @param base the base number of the exponent operation
+/// @param exp the exponent
/// @returns the value of `base` raised to the power `exp`, or an empty optional if the operation
/// cannot be performed.
template <typename FloatingPointT,
@@ -625,6 +654,7 @@
return result;
}
+/// Re-enables the maybe-uninitialized compiler warnings
TINT_END_DISABLE_WARNING(MAYBE_UNINITIALIZED);
} // namespace tint
diff --git a/src/tint/tint.cc b/src/tint/tint.cc
index b2e3cfa..7ed40af 100644
--- a/src/tint/tint.cc
+++ b/src/tint/tint.cc
@@ -16,6 +16,7 @@
namespace tint {
+/// Initialize initializes the Tint library. Call before using the Tint API.
void Initialize() {
#if TINT_BUILD_WGSL_WRITER
// Register the Program printer. This is used for debugging purposes.
@@ -29,6 +30,7 @@
#endif
}
+/// Shutdown uninitializes the Tint library. Call after using the Tint API.
void Shutdown() {
// Currently no-op, but may release tint resources in the future.
}
diff --git a/src/tint/utils/containers/reverse.h b/src/tint/utils/containers/reverse.h
index e4c4def..78ce709 100644
--- a/src/tint/utils/containers/reverse.h
+++ b/src/tint/utils/containers/reverse.h
@@ -52,6 +52,8 @@
/// for (auto v : tint::Reverse(vec)) {
/// }
/// ```
+/// @param iterable the object to iterate
+/// @returns the reverse iterable object
template <typename T>
detail::ReverseIterable<T> Reverse(T&& iterable) {
return {iterable};
diff --git a/src/tint/utils/containers/slice.h b/src/tint/utils/containers/slice.h
index d25c1de..259ae6a 100644
--- a/src/tint/utils/containers/slice.h
+++ b/src/tint/utils/containers/slice.h
@@ -250,6 +250,7 @@
};
/// Deduction guide for Slice from c-array
+/// @param elements the input elements
template <typename T, size_t N>
Slice(T (&elements)[N]) -> Slice<T>;
diff --git a/src/tint/utils/containers/transform.h b/src/tint/utils/containers/transform.h
index 463376c..86d1637 100644
--- a/src/tint/utils/containers/transform.h
+++ b/src/tint/utils/containers/transform.h
@@ -24,6 +24,8 @@
#include "src/tint/utils/traits/traits.h"
namespace tint {
+//! @cond Doxygen_Suppress
+// Doxygen gets confused by Transform()'s SFINAE
/// Transform performs an element-wise transformation of a vector.
/// @param in the input vector.
@@ -172,4 +174,5 @@
} // namespace tint
+//! @endcond
#endif // SRC_TINT_UTILS_CONTAINERS_TRANSFORM_H_
diff --git a/src/tint/utils/containers/vector.h b/src/tint/utils/containers/vector.h
index c437731..dc29721 100644
--- a/src/tint/utils/containers/vector.h
+++ b/src/tint/utils/containers/vector.h
@@ -803,6 +803,8 @@
};
/// Helper for converting a Vector to a std::vector.
+/// @param vector the input vector
+/// @return the converted vector
/// @note This helper exists to help code migration. Avoid if possible.
template <typename T, size_t N>
std::vector<T> ToStdVector(const Vector<T, N>& vector) {
@@ -815,6 +817,8 @@
}
/// Helper for converting a std::vector to a Vector.
+/// @param vector the input vector
+/// @return the converted vector
/// @note This helper exists to help code migration. Avoid if possible.
template <typename T, size_t N = 0>
Vector<T, N> ToVector(const std::vector<T>& vector) {
diff --git a/src/tint/utils/macros/defer.h b/src/tint/utils/macros/defer.h
index a6f51a9..9ec9bf5 100644
--- a/src/tint/utils/macros/defer.h
+++ b/src/tint/utils/macros/defer.h
@@ -45,6 +45,7 @@
/// Constructor
/// @param f the function to call when the Defer is destructed
+/// @return the defer object
template <typename F>
inline Defer<F> MakeDefer(F&& f) {
return Defer<F>(std::forward<F>(f));
diff --git a/src/tint/utils/math/crc32.h b/src/tint/utils/math/crc32.h
index 3113edb..4854ab8 100644
--- a/src/tint/utils/math/crc32.h
+++ b/src/tint/utils/math/crc32.h
@@ -20,6 +20,7 @@
namespace tint {
+/// CRC32 immutable lookup table data.
constexpr uint32_t kCRC32LUT[] = {
0, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3,
0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91,
@@ -54,6 +55,7 @@
0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 0xcdd70693, 0x54de5729, 0x23d967bf,
0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d};
+/// @param s the null-terminated string
/// @returns the CRC32 of the string @p s.
/// @note this function can be used to calculate the CRC32 of a string literal
/// at compile time.
@@ -66,6 +68,8 @@
return crc ^ 0xffffffff;
}
+/// @param ptr a pointer to the start of the data
+/// @param size the number of bytes of the data
/// @returns the CRC32 of the data at @p ptr of size @p size.
inline uint32_t CRC32(const void* ptr, size_t size) {
auto* p = static_cast<const uint8_t*>(ptr);
diff --git a/src/tint/utils/math/hash.h b/src/tint/utils/math/hash.h
index bdaaabe..2b8d42f 100644
--- a/src/tint/utils/math/hash.h
+++ b/src/tint/utils/math/hash.h
@@ -190,6 +190,7 @@
}
};
+/// @param args the arguments to hash
/// @returns a hash of the variadic list of arguments.
/// The returned hash is dependent on the order of the arguments.
template <typename... ARGS>
@@ -205,6 +206,8 @@
}
}
+/// @param hash the hash value to combine with
+/// @param values the values to hash
/// @returns a hash of the variadic list of arguments.
/// The returned hash is dependent on the order of the arguments.
template <typename... ARGS>
diff --git a/src/tint/utils/memory/bump_allocator.h b/src/tint/utils/memory/bump_allocator.h
index db78644..5d4f594 100644
--- a/src/tint/utils/memory/bump_allocator.h
+++ b/src/tint/utils/memory/bump_allocator.h
@@ -24,11 +24,11 @@
namespace tint {
-constexpr size_t kBlockSize = 64 * 1024;
-
/// A allocator for chunks of memory. The memory is owned by the BumpAllocator. When the
/// BumpAllocator is freed all of the allocated memory is freed.
class BumpAllocator {
+ static constexpr size_t kBlockSize = 64 * 1024;
+
/// Block is linked list of memory blocks.
/// Blocks are allocated out of heap memory.
struct Block {
diff --git a/src/tint/utils/result/result.h b/src/tint/utils/result/result.h
index ad7e864..aab5048 100644
--- a/src/tint/utils/result/result.h
+++ b/src/tint/utils/result/result.h
@@ -32,6 +32,7 @@
/// Empty structure used as the default FAILURE_TYPE for a Result.
struct FailureType {};
+/// An instance of FailureType which can be used as a generic failure value by Result
static constexpr const FailureType Failure;
/// Result is a helper for functions that need to return a value, or an failure value.
diff --git a/src/tint/utils/text/parse_num.h b/src/tint/utils/text/parse_num.h
index dc8af52..b0416a8 100644
--- a/src/tint/utils/text/parse_num.h
+++ b/src/tint/utils/text/parse_num.h
@@ -79,6 +79,7 @@
/// @returns the string @p str parsed as a uint8_t
Result<uint8_t, ParseNumberError> ParseUint8(std::string_view str);
+/// Disables the false-positive unreachable-code compiler warnings
TINT_BEGIN_DISABLE_WARNING(UNREACHABLE_CODE);
/// @param str the string
@@ -124,6 +125,7 @@
return ParseNumberError::kUnparsable;
}
+/// Re-enables the unreachable-code compiler warnings
TINT_END_DISABLE_WARNING(UNREACHABLE_CODE);
} // namespace tint
diff --git a/src/tint/utils/text/string.h b/src/tint/utils/text/string.h
index 8a6987b..1a3d74e 100644
--- a/src/tint/utils/text/string.h
+++ b/src/tint/utils/text/string.h
@@ -159,12 +159,12 @@
/// @param c the character to test
/// @returns true if @p c is one of the following:
-/// * space (' ')
-/// * form feed ('\f')
-/// * line feed ('\n')
-/// * carriage return ('\r')
-/// * horizontal tab ('\t')
-/// * vertical tab ('\v')
+/// * space
+/// * form feed
+/// * line feed
+/// * carriage return
+/// * horizontal tab
+/// * vertical tab
inline bool IsSpace(char c) {
return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' || c == '\v';
}
@@ -192,6 +192,7 @@
return out;
}
+/// @param str the string to quote
/// @returns @p str quoted with <code>'</code>
inline std::string Quote(std::string_view str) {
return "'" + std::string(str) + "'";
