Give clearer names to template parameters

include/backtrace.hpp

@@ -25,15 +25,15 @@ extern Tracing tracing;
 
 bool trace_ParseTraceDepth(char const *arg);
 
-template<typename T, typename M, typename N>
-void trace_PrintBacktrace(std::vector<T> const &stack, M getName, N getLineNo) {
+template<typename NodeT, typename NameFnT, typename LineNoFnT>
+void trace_PrintBacktrace(std::vector<NodeT> const &stack, NameFnT getName, LineNoFnT getLineNo) {
 	size_t n = stack.size();
 	if (n == 0) {
 		return; // LCOV_EXCL_LINE
 	}
 
 	auto printLocation = [&](size_t i) {
-		T const &item = stack[n - i - 1];
+		NodeT const &item = stack[n - i - 1];
 		style_Reset(stderr);
 		if (!tracing.collapse) {
 			fputs("   ", stderr); // Just three spaces; the fourth will be printed next

include/diagnostics.hpp

@@ -30,35 +30,35 @@ struct WarningState {
 
 std::pair<WarningState, std::optional<uint32_t>> getInitialWarningState(std::string &flag);
 
-template<typename L>
+template<typename LevelEnumT>
 struct WarningFlag {
 	char const *name;
-	L level;
+	LevelEnumT level;
 };
 
 enum WarningBehavior { DISABLED, ENABLED, ERROR };
 
-template<typename W>
+template<typename WarningEnumT>
 struct ParamWarning {
-	W firstID;
-	W lastID;
+	WarningEnumT firstID;
+	WarningEnumT lastID;
 	uint8_t defaultLevel;
 };
 
-template<typename W>
+template<typename WarningEnumT>
 struct DiagnosticsState {
-	WarningState flagStates[W::NB_WARNINGS];
-	WarningState metaStates[W::NB_WARNINGS];
+	WarningState flagStates[WarningEnumT::NB_WARNINGS];
+	WarningState metaStates[WarningEnumT::NB_WARNINGS];
 	bool warningsEnabled = true;
 	bool warningsAreErrors = false;
 };
 
-template<typename L, typename W>
+template<typename LevelEnumT, typename WarningEnumT>
 struct Diagnostics {
-	std::vector<WarningFlag<L>> metaWarnings;
-	std::vector<WarningFlag<L>> warningFlags;
-	std::vector<ParamWarning<W>> paramWarnings;
-	DiagnosticsState<W> state;
+	std::vector<WarningFlag<LevelEnumT>> metaWarnings;
+	std::vector<WarningFlag<LevelEnumT>> warningFlags;
+	std::vector<ParamWarning<WarningEnumT>> paramWarnings;
+	DiagnosticsState<WarningEnumT> state;
 	uint64_t nbErrors;
 
 	void incrementErrors() {
@@ -67,12 +67,12 @@ struct Diagnostics {
 		}
 	}
 
-	WarningBehavior getWarningBehavior(W id) const;
+	WarningBehavior getWarningBehavior(WarningEnumT id) const;
 	void processWarningFlag(char const *flag);
 };
 
-template<typename L, typename W>
-WarningBehavior Diagnostics<L, W>::getWarningBehavior(W id) const {
+template<typename LevelEnumT, typename WarningEnumT>
+WarningBehavior Diagnostics<LevelEnumT, WarningEnumT>::getWarningBehavior(WarningEnumT id) const {
 	// Check if warnings are globally disabled
 	if (!state.warningsEnabled) {
 		return WarningBehavior::DISABLED;
@@ -112,7 +112,7 @@ WarningBehavior Diagnostics<L, W>::getWarningBehavior(W id) const {
 	}
 
 	// If no meta flag is specified, check the default state of this warning flag
-	if (warningFlags[id].level == L::LEVEL_DEFAULT) { // enabled by default
+	if (warningFlags[id].level == LevelEnumT::LEVEL_DEFAULT) { // enabled by default
 		return enabledBehavior;
 	}
 
@@ -120,8 +120,8 @@ WarningBehavior Diagnostics<L, W>::getWarningBehavior(W id) const {
 	return WarningBehavior::DISABLED;
 }
 
-template<typename L, typename W>
-void Diagnostics<L, W>::processWarningFlag(char const *flag) {
+template<typename LevelEnumT, typename WarningEnumT>
+void Diagnostics<LevelEnumT, WarningEnumT>::processWarningFlag(char const *flag) {
 	std::string rootFlag = flag;
 
 	// Check for `-Werror` or `-Wno-error` to return early
@@ -140,8 +140,8 @@ void Diagnostics<L, W>::processWarningFlag(char const *flag) {
 	// Try to match the flag against a parametric warning
 	// If there was an equals sign, it will have set `param`; if not, `param` will be 0,
 	// which applies to all levels
-	for (ParamWarning<W> const &paramWarning : paramWarnings) {
-		W baseID = paramWarning.firstID;
+	for (ParamWarning<WarningEnumT> const &paramWarning : paramWarnings) {
+		WarningEnumT baseID = paramWarning.firstID;
 		uint8_t maxParam = paramWarning.lastID - baseID + 1;
 		assume(paramWarning.defaultLevel <= maxParam);
 
@@ -183,13 +183,13 @@ void Diagnostics<L, W>::processWarningFlag(char const *flag) {
 	}
 
 	// Try to match against a "meta" warning
-	for (WarningFlag<L> const &metaWarning : metaWarnings) {
+	for (WarningFlag<LevelEnumT> const &metaWarning : metaWarnings) {
 		if (rootFlag != metaWarning.name) {
 			continue;
 		}
 
 		// Set each of the warning flags that meets this level
-		for (W id : EnumSeq(W::NB_WARNINGS)) {
+		for (WarningEnumT id : EnumSeq(WarningEnumT::NB_WARNINGS)) {
 			if (metaWarning.level >= warningFlags[id].level) {
 				state.metaStates[id].update(flagState);
 			}
@@ -198,7 +198,7 @@ void Diagnostics<L, W>::processWarningFlag(char const *flag) {
 	}
 
 	// Try to match against a "normal" flag
-	for (W id : EnumSeq(W::NB_PLAIN_WARNINGS)) {
+	for (WarningEnumT id : EnumSeq(WarningEnumT::NB_PLAIN_WARNINGS)) {
 		if (rootFlag == warningFlags[id].name) {
 			state.flagStates[id].update(flagState);
 			return;

include/helpers.hpp

@@ -100,16 +100,16 @@ static inline int clz(unsigned int x) {
 #define RRANGE(s) std::rbegin(s), std::rend(s)
 
 // MSVC does not inline `strlen()` or `.length()` of a constant string
-template<int N>
-static constexpr int literal_strlen(char const (&)[N]) {
-	return N - 1;
+template<int SizeOfString>
+static constexpr int literal_strlen(char const (&)[SizeOfString]) {
+	return SizeOfString - 1; // Don't count the ending '\0'
 }
 
 // For ad-hoc RAII in place of a `defer` statement or cross-platform `__attribute__((cleanup))`
-template<typename T>
+template<typename DeferredFnT>
 struct Defer {
-	T deferred;
-	Defer(T func) : deferred(func) {}
+	DeferredFnT deferred;
+	Defer(DeferredFnT func) : deferred(func) {}
 	~Defer() { deferred(); }
 };
 

include/itertools.hpp

@@ -12,29 +12,31 @@
 #include <unordered_map>
 #include <utility>
 
-template<typename T>
+// A wrapper around iterables to reverse their iteration order; used in `for`-each loops.
+template<typename IterableT>
 struct ReversedIterable {
-	T &_iterable;
+	IterableT &_iterable;
 };
 
-template<typename T>
-auto begin(ReversedIterable<T> r) {
+template<typename IterableT>
+auto begin(ReversedIterable<IterableT> r) {
 	return std::rbegin(r._iterable);
 }
 
-template<typename T>
-auto end(ReversedIterable<T> r) {
+template<typename IterableT>
+auto end(ReversedIterable<IterableT> r) {
 	return std::rend(r._iterable);
 }
 
-template<typename T>
-ReversedIterable<T> reversed(T &&_iterable) {
+template<typename IterableT>
+ReversedIterable<IterableT> reversed(IterableT &&_iterable) {
 	return {_iterable};
 }
 
-template<typename T>
+// A map from `std::string` keys to `ItemT` items, iterable in the order the items were inserted.
+template<typename ItemT>
 class InsertionOrderedMap {
-	std::deque<T> list;
+	std::deque<ItemT> list;
 	std::unordered_map<std::string, size_t> map; // Indexes into `list`
 
 public:
@@ -44,25 +46,25 @@ public:
 
 	bool contains(std::string const &name) const { return map.find(name) != map.end(); }
 
-	T &operator[](size_t i) { return list[i]; }
+	ItemT &operator[](size_t i) { return list[i]; }
 
 	typename decltype(list)::iterator begin() { return list.begin(); }
 	typename decltype(list)::iterator end() { return list.end(); }
 	typename decltype(list)::const_iterator begin() const { return list.begin(); }
 	typename decltype(list)::const_iterator end() const { return list.end(); }
 
-	T &add(std::string const &name) {
+	ItemT &add(std::string const &name) {
 		map[name] = list.size();
 		return list.emplace_back();
 	}
 
-	T &add(std::string const &name, T &&value) {
+	ItemT &add(std::string const &name, ItemT &&value) {
 		map[name] = list.size();
 		list.emplace_back(std::move(value));
 		return list.back();
 	}
 
-	T &addAnonymous() {
+	ItemT &addAnonymous() {
 		// Add the new item to the list, but do not update the map
 		return list.emplace_back();
 	}
@@ -75,43 +77,45 @@ public:
 	}
 };
 
-template<typename T>
+// An iterable of `enum` values in the half-open range [start, stop).
+template<typename EnumT>
 class EnumSeq {
-	T _start;
-	T _stop;
+	EnumT _start;
+	EnumT _stop;
 
 	class Iterator {
-		T _value;
+		EnumT _value;
 
 	public:
-		explicit Iterator(T value) : _value(value) {}
+		explicit Iterator(EnumT value) : _value(value) {}
 
 		Iterator &operator++() {
-			_value = static_cast<T>(_value + 1);
+			_value = static_cast<EnumT>(_value + 1);
 			return *this;
 		}
 
-		T operator*() const { return _value; }
+		EnumT operator*() const { return _value; }
 
 		bool operator==(Iterator const &rhs) const { return _value == rhs._value; }
 	};
 
 public:
-	explicit EnumSeq(T stop) : _start(static_cast<T>(0)), _stop(stop) {}
-	explicit EnumSeq(T start, T stop) : _start(start), _stop(stop) {}
+	explicit EnumSeq(EnumT stop) : _start(static_cast<EnumT>(0)), _stop(stop) {}
+	explicit EnumSeq(EnumT start, EnumT stop) : _start(start), _stop(stop) {}
 
 	Iterator begin() { return Iterator(_start); }
 	Iterator end() { return Iterator(_stop); }
 };
 
+// Only needed inside `ZipContainer` below.
 // This is not a fully generic implementation; its current use cases only require for-loop behavior.
 // We also assume that all iterators have the same length.
-template<typename... Ts>
+template<typename... IteratorTs>
 class ZipIterator {
-	std::tuple<Ts...> _iters;
+	std::tuple<IteratorTs...> _iters;
 
 public:
-	explicit ZipIterator(std::tuple<Ts...> &&iters) : _iters(iters) {}
+	explicit ZipIterator(std::tuple<IteratorTs...> &&iters) : _iters(iters) {}
 
 	ZipIterator &operator++() {
 		std::apply([](auto &&...it) { (++it, ...); }, _iters);
@@ -129,12 +133,14 @@ public:
 	}
 };
 
-template<typename... Ts>
+// Only needed inside `zip` below.
+template<typename... IterableTs>
 class ZipContainer {
-	std::tuple<Ts...> _containers;
+	std::tuple<IterableTs...> _containers;
 
 public:
-	explicit ZipContainer(Ts &&...containers) : _containers(std::forward<Ts>(containers)...) {}
+	explicit ZipContainer(IterableTs &&...containers)
+	    : _containers(std::forward<IterableTs>(containers)...) {}
 
 	auto begin() {
 		return ZipIterator(std::apply(
@@ -157,15 +163,19 @@ public:
 	}
 };
 
+// Only needed inside `zip` below.
 // Take ownership of objects and rvalue refs passed to us, but not lvalue refs
-template<typename T>
-using Holder = std::
-    conditional_t<std::is_lvalue_reference_v<T>, T, std::remove_cv_t<std::remove_reference_t<T>>>;
+template<typename IterableT>
+using ZipHolder = std::conditional_t<
+    std::is_lvalue_reference_v<IterableT>,
+    IterableT,
+    std::remove_cv_t<std::remove_reference_t<IterableT>>>;
 
+// Iterates over N containers at once, yielding tuples of N items at a time.
 // Does the same number of iterations as the first container's iterator!
-template<typename... Ts>
-static constexpr auto zip(Ts &&...cs) {
-	return ZipContainer<Holder<Ts>...>(std::forward<Ts>(cs)...);
+template<typename... IterableTs>
+static constexpr auto zip(IterableTs &&...containers) {
+	return ZipContainer<ZipHolder<IterableTs>...>(std::forward<IterableTs>(containers)...);
 }
 
 #endif // RGBDS_ITERTOOLS_HPP

include/link/section.hpp

@@ -52,28 +52,28 @@ struct Section {
 
 private:
 	// Template class for both const and non-const iterators over the "pieces" of this section
-	template<typename T>
+	template<typename SectionT>
 	class PiecesIterable {
-		T *_firstPiece;
+		SectionT *_firstPiece;
 
 		class Iterator {
-			T *_piece;
+			SectionT *_piece;
 
 		public:
-			explicit Iterator(T *piece) : _piece(piece) {}
+			explicit Iterator(SectionT *piece) : _piece(piece) {}
 
 			Iterator &operator++() {
 				_piece = _piece->nextPiece.get();
 				return *this;
 			}
 
-			T &operator*() const { return *_piece; }
+			SectionT &operator*() const { return *_piece; }
 
 			bool operator==(Iterator const &rhs) const { return _piece == rhs._piece; }
 		};
 
 	public:
-		explicit PiecesIterable(T *firstPiece) : _firstPiece(firstPiece) {}
+		explicit PiecesIterable(SectionT *firstPiece) : _firstPiece(firstPiece) {}
 
 		Iterator begin() { return Iterator(_firstPiece); }
 		Iterator end() { return Iterator(nullptr); }

include/util.hpp

@@ -64,7 +64,8 @@ struct Uppercase {
 	}
 };
 
-template<typename T>
-using UpperMap = std::unordered_map<std::string, T, Uppercase, Uppercase>;
+// An unordered map from case-insensitive `std::string` keys to `ItemT` items
+template<typename ItemT>
+using UpperMap = std::unordered_map<std::string, ItemT, Uppercase, Uppercase>;
 
 #endif // RGBDS_UTIL_HPP