Give clearer names to template parameters

.clang-format

@@ -71,6 +71,7 @@ Language: Cpp
 MaxEmptyLinesToKeep: 1
 NamespaceIndentation: None
 PPIndentWidth: -1
+PenaltyBreakScopeResolution: 1000
 PointerAlignment: Right
 QualifierAlignment: Right
 ReflowComments: true

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

src/asm/charmap.cpp

@@ -38,8 +38,8 @@ struct Charmap {
 };
 
 // Traverse the trie depth-first to derive the character mappings in definition order
-template<typename F>
-bool forEachChar(Charmap const &charmap, F callback) {
+template<typename CallbackFnT>
+bool forEachChar(Charmap const &charmap, CallbackFnT callback) {
 	// clang-format off: nested initializers
 	for (std::stack<std::pair<size_t, std::string>> prefixes({{0, ""}}); !prefixes.empty();) {
 		// clang-format on

src/asm/lexer.cpp

@@ -816,8 +816,8 @@ static int nextChar() {
 	return peek();
 }
 
-template<typename P>
-static int skipChars(P predicate) {
+template<typename PredicateFnT>
+static int skipChars(PredicateFnT predicate) {
 	int c = peek();
 	while (predicate(c)) {
 		c = nextChar();
@@ -2281,8 +2281,8 @@ yy::parser::symbol_type yylex() {
 	}
 }
 
-template<typename F>
-static Capture makeCapture(char const *name, F callback) {
+template<typename CallbackFnT>
+static Capture makeCapture(char const *name, CallbackFnT callback) {
 	// Due to parser internals, it reads the EOL after the expression before calling this.
 	// Thus, we don't need to keep one in the buffer afterwards.
 	// The following assumption checks that.

src/asm/parser.y

@@ -57,8 +57,10 @@
 
 	yy::parser::symbol_type yylex(); // Provided by lexer.cpp
 
-	template <typename N, typename S>
-	static auto handleSymbolByType(std::string const &symName, N numCallback, S strCallback) {
+	template<typename NumCallbackFnT, typename StrCallbackFnT>
+	static auto handleSymbolByType(
+	    std::string const &symName, NumCallbackFnT numCallback, StrCallbackFnT strCallback
+	) {
 		if (Symbol *sym = sym_FindScopedSymbol(symName); sym && sym->type == SYM_EQUS) {
 			return strCallback(*sym->getEqus());
 		} else {

src/gfx/pal_packing.cpp

@@ -70,7 +70,7 @@ public:
 
 private:
 	// Template class for both const and non-const iterators over the non-empty `_assigned` slots
-	template<typename I, template<typename> typename Constness>
+	template<typename IteratorT, template<typename> typename Constness>
 	class AssignedSetsIter {
 	public:
 		friend class AssignedSets;
@@ -84,7 +84,7 @@ private:
 
 	private:
 		Constness<decltype(_assigned)> *_array = nullptr;
-		I _iter{};
+		IteratorT _iter{};
 
 		AssignedSetsIter(decltype(_array) array, decltype(_iter) &&iter)
 		    : _array(array), _iter(iter) {}
@@ -164,11 +164,11 @@ public:
 	size_t nbColorSets() const { return std::distance(RANGE(*this)); }
 
 private:
-	template<typename I>
+	template<typename IteratorT>
 	static void addUniqueColors(
 	    std::unordered_set<uint16_t> &colors,
-	    I iter,
-	    I const &end,
+	    IteratorT iter,
+	    IteratorT const &end,
 	    std::vector<ColorSet> const &colorSets
 	) {
 		for (; iter != end; ++iter) {
@@ -240,18 +240,20 @@ public:
 	}
 
 	// Computes the "relative size" of a set of color sets on this palette
-	template<typename I>
-	size_t combinedVolume(I &&begin, I const &end, std::vector<ColorSet> const &colorSets) const {
+	template<typename IteratorT>
+	size_t combinedVolume(
+	    IteratorT &&begin, IteratorT const &end, std::vector<ColorSet> const &colorSets
+	) const {
 		std::unordered_set<uint16_t> &colors = uniqueColors();
-		addUniqueColors(colors, std::forward<I>(begin), end, colorSets);
+		addUniqueColors(colors, std::forward<IteratorT>(begin), end, colorSets);
 		return colors.size();
 	}
 
 	// Computes the "relative size" of a set of colors on this palette
-	template<typename I>
-	size_t combinedVolume(I &&begin, I &&end) const {
+	template<typename IteratorT>
+	size_t combinedVolume(IteratorT &&begin, IteratorT &&end) const {
 		std::unordered_set<uint16_t> &colors = uniqueColors();
-		colors.insert(std::forward<I>(begin), std::forward<I>(end));
+		colors.insert(std::forward<IteratorT>(begin), std::forward<IteratorT>(end));
 		return colors.size();
 	}
 };

src/gfx/pal_spec.cpp

@@ -210,15 +210,15 @@ static void warnExtraColors(
 }
 
 // Parses the initial part of a string_view, advancing the "read index" as it does
-template<typename U> // Should be uint*_t
-static std::optional<U> parseDec(std::string const &str, size_t &n) {
+template<typename UintT> // Should be uint*_t
+static std::optional<UintT> parseDec(std::string const &str, size_t &n) {
 	uintmax_t value = 0;
 	auto result = std::from_chars(str.data() + n, str.data() + str.length(), value);
 	if (static_cast<bool>(result.ec)) {
 		return std::nullopt;
 	}
 	n = result.ptr - str.data();
-	return std::optional<U>{value};
+	return std::optional<UintT>{value};
 }
 
 static std::optional<Rgba> parseColor(std::string const &str, size_t &n, uint16_t i) {

src/link/output.cpp

@@ -314,8 +314,8 @@ static bool compareSymbols(SortedSymbol const &sym1, SortedSymbol const &sym2) {
 	       < std::tie(sym2.addr, sym2_local, sym2.parentAddr, sym2_name);
 }
 
-template<typename F>
-static void forEachSortedSection(SortedSections const &bankSections, F callback) {
+template<typename CallbackFnT>
+static void forEachSortedSection(SortedSections const &bankSections, CallbackFnT callback) {
 	for (Section const *sect : bankSections.zeroLenSections) {
 		for (Section const &piece : sect->pieces()) {
 			callback(piece);
@@ -415,8 +415,8 @@ static void writeSectionName(std::string const &name, FILE *file) {
 	}
 }
 
-template<typename F>
-uint16_t forEachSection(SortedSections const &sectList, F callback) {
+template<typename CallbackFnT>
+uint16_t forEachSection(SortedSections const &sectList, CallbackFnT callback) {
 	uint16_t used = 0;
 	auto section = sectList.sections.begin();
 	auto zeroLenSection = sectList.zeroLenSections.begin();