Remove redundant @-style doc comment tags (#1641)

include/link/object.hpp

@@ -4,12 +4,9 @@
 #define RGBDS_LINK_OBJECT_HPP
 
 // Read an object (.o) file, and add its info to the data structures.
-// @param fileName A path to the object file to be read
+void obj_ReadFile(char const *fileName, unsigned int fileID);
-// @param i The ID of the file
-void obj_ReadFile(char const *fileName, unsigned int i);
 
 // Sets up object file reading
-// @param nbFiles The number of object files that will be read
 void obj_Setup(unsigned int nbFiles);
 
 #endif // RGBDS_LINK_OBJECT_HPP

include/link/output.hpp

@@ -6,12 +6,9 @@
 struct Section;
 
 // Registers a section for output.
-// @param section The section to add
 void out_AddSection(Section const &section);
 
 // Finds an assigned section overlapping another one.
-// @param section The section that is being overlapped
-// @return A section overlapping it
 Section const *out_OverlappingSection(Section const &section);
 
 // Writes all output (bin, sym, map) files.

include/link/patch.hpp

@@ -4,7 +4,6 @@
 #define RGBDS_LINK_PATCH_HPP
 
 // Checks all assertions
-// @return true if assertion failed
 void patch_CheckAssertions();
 
 // Applies all SECTIONs' patches to them

include/link/section.hpp

@@ -67,16 +67,12 @@ extern std::deque<Assertion> assertions;
 
 // Execute a callback for each section currently registered.
 // This is to avoid exposing the data structure in which sections are stored.
-// @param callback The function to call for each structure.
 void sect_ForEach(void (*callback)(Section &));
 
 // Registers a section to be processed.
-// @param section The section to register.
 void sect_AddSection(std::unique_ptr<Section> &&section);
 
 // Finds a section by its name.
-// @param name The name of the section to look for
-// @return A pointer to the section, or `nullptr` if it wasn't found
 Section *sect_GetSection(std::string const &name);
 
 // Checks if all sections meet reasonable criteria, such as max size

include/link/symbol.hpp

@@ -42,8 +42,6 @@ void sym_ForEach(void (*callback)(Symbol &));
 void sym_AddSymbol(Symbol &symbol);
 
 // Finds a symbol in all the defined symbols.
-// @param name The name of the symbol to look for
-// @return A pointer to the symbol, or `nullptr` if not found.
 Symbol *sym_GetSymbol(std::string const &name);
 
 void sym_DumpLocalAliasedSymbols(std::string const &name);

include/linkdefs.hpp

@@ -94,21 +94,17 @@ extern struct SectionTypeInfo {
 
 // Tells whether a section has data in its object file definition,
 // depending on type.
-// @param type The section's type
-// @return `true` if the section's definition includes data
 static inline bool sect_HasData(SectionType type) {
 	assume(type != SECTTYPE_INVALID);
 	return type == SECTTYPE_ROM0 || type == SECTTYPE_ROMX;
 }
 
-// Computes a memory region's end address (last byte), eg. 0x7FFF
+// Returns a memory region's end address (last byte), e.g. 0x7FFF
-// @return The address of the last byte in that memory region
 static inline uint16_t endaddr(SectionType type) {
 	return sectionTypeInfo[type].startAddr + sectionTypeInfo[type].size - 1;
 }
 
-// Computes a memory region's number of banks
+// Returns a memory region's number of banks, or 1 for regions without banking
-// @return The number of banks, 1 for regions without banking
 static inline uint32_t nbbanks(SectionType type) {
 	return sectionTypeInfo[type].lastBank - sectionTypeInfo[type].firstBank + 1;
 }

src/asm/rpn.cpp

@@ -228,9 +228,8 @@ static bool tryConstLogNot(Expression const &expr) {
 	return knownBits != 0;
 }
 
-// Attempts to compute a constant LOW() from non-constant argument
+// Returns a constant LOW() from non-constant argument, or -1 if it cannot be computed.
 // This is possible if the argument is a symbol belonging to an `ALIGN[8]` section.
-// @return The constant `LOW(expr)` result if it can be computed, or -1 otherwise.
 static int32_t tryConstLow(Expression const &expr) {
 	Symbol const *sym = expr.symbolOf();
 	if (!sym || !sym->getSection() || !sym->isDefined()) {
@@ -253,10 +252,9 @@ static int32_t tryConstLow(Expression const &expr) {
 	return (symbolOfs + sect.alignOfs) & 0xFF;
 }
 
-// Attempts to compute a constant binary AND with one non-constant operands
+// Returns a constant binary AND with one non-constant operand, or -1 if it cannot be computed.
 // This is possible if one operand is a symbol belonging to an `ALIGN[N]` section, and the other is
 // a constant that only keeps (some of) the lower N bits.
-// @return The constant `lhs & rhs` result if it can be computed, or -1 otherwise.
 static int32_t tryConstMask(Expression const &lhs, Expression const &rhs) {
 	Symbol const *lhsSymbol = lhs.symbolOf();
 	Symbol const *rhsSymbol = lhsSymbol ? nullptr : rhs.symbolOf();

src/fix/main.cpp

@@ -185,7 +185,6 @@ static void printAcceptedMBCNames() {
 
 static uint8_t tpp1Rev[2];
 
-// @return False on failure
 static bool readMBCSlice(char const *&name, char const *expected) {
 	while (*expected) {
 		char c = *name++;
@@ -853,10 +852,6 @@ static ssize_t writeBytes(int fd, uint8_t *buf, size_t len) {
 	return total;
 }
 
-// @param rom0 A pointer to rom0
-// @param addr What address to check
-// @param fixedByte The fixed byte at the address
-// @param areaName Name to be displayed in the warning message
 static void overwriteByte(uint8_t *rom0, uint16_t addr, uint8_t fixedByte, char const *areaName) {
 	uint8_t origByte = rom0[addr];
 
@@ -867,11 +862,6 @@ static void overwriteByte(uint8_t *rom0, uint16_t addr, uint8_t fixedByte, char
 	rom0[addr] = fixedByte;
 }
 
-// @param rom0 A pointer to rom0
-// @param startAddr What address to begin checking from
-// @param fixed The fixed bytes at the address
-// @param size How many bytes to check
-// @param areaName Name to be displayed in the warning message
 static void overwriteBytes(
     uint8_t *rom0, uint16_t startAddr, uint8_t const *fixed, uint8_t size, char const *areaName
 ) {
@@ -889,10 +879,6 @@ static void overwriteBytes(
 	memcpy(&rom0[startAddr], fixed, size);
 }
 
-// @param input File descriptor to be used for reading
-// @param output File descriptor to be used for writing, may be equal to `input`
-// @param name The file's name, to be displayed for error output
-// @param fileSize The file's size if known, 0 if not.
 static void processFile(int input, int output, char const *name, off_t fileSize) {
 	// Both of these should be true for seekable files, and neither otherwise
 	if (input == output) {

src/gfx/main.cpp

@@ -270,8 +270,7 @@ static void registerInput(char const *arg) {
 	}
 }
 
-// Turn an "at-file"'s contents into an argv that `getopt` can handle
+// Turn an at-file's contents into an argv that `getopt` can handle, appending them to `argPool`.
-// @param argPool Argument characters will be appended to this vector, for storage purposes.
 static std::vector<size_t> readAtFile(std::string const &path, std::vector<char> &argPool) {
 	File file;
 	if (!file.open(path, std::ios_base::in)) {

src/gfx/pal_spec.cpp

@@ -189,8 +189,8 @@ static T readLE(U const *bytes) {
 	return val;
 }
 
-// **Appends** the first line read from `file` to the end of the provided `buffer`.
+// Appends the first line read from `file` to the end of the provided `buffer`.
-// @return true if a line was read.
+// Returns true if a line was read.
 [[gnu::warn_unused_result]]
 static bool readLine(std::filebuf &file, std::string &buffer) {
 	assume(buffer.empty());

src/link/assign.cpp

@@ -49,8 +49,6 @@ static void initFreeSpace() {
 }
 
 // Assigns a section to a given memory location
-// @param section The section to assign
-// @param location The location to assign the section to
 static void assignSection(Section &section, MemoryLocation const &location) {
 	// Propagate the assigned location to all UNIONs/FRAGMENTs
 	// so `jr` patches in them will have the correct offset
@@ -67,10 +65,6 @@ static void assignSection(Section &section, MemoryLocation const &location) {
 // Checks whether a given location is suitable for placing a given section
 // This checks not only that the location has enough room for the section, but
 // also that the constraints (alignment...) are respected.
-// @param section The section to be placed
-// @param freeSpace The candidate free space to place the section into
-// @param location The location to attempt placing the section at
-// @return True if the location is suitable, false otherwise.
 static bool isLocationSuitable(
     Section const &section, FreeSpace const &freeSpace, MemoryLocation const &location
 ) {
@@ -89,11 +83,8 @@ static bool isLocationSuitable(
 	return location.address + section.size <= freeSpace.address + freeSpace.size;
 }
 
-// Finds a suitable location to place a section at.
+// Returns a suitable free space index into `memory[section->type]` at which to place the given
-// @param section The section to be placed
+// section, or -1 if none was found.
-// @param location A pointer to a memory location that will be filled
-// @return The index into `memory[section->type]` of the free space encompassing the location,
-//         or -1 if none was found
 static ssize_t getPlacement(Section const &section, MemoryLocation &location) {
 	SectionTypeInfo const &typeInfo = sectionTypeInfo[section.type];
 
@@ -214,9 +205,7 @@ static ssize_t getPlacement(Section const &section, MemoryLocation &location) {
 }
 
 // Places a section in a suitable location, or error out if it fails to.
-// @warning Due to the implemented algorithm, this should be called with
+// Due to the implemented algorithm, this should be called with sections of decreasing size!
-//          sections of decreasing size.
-// @param section The section to place
 static void placeSection(Section &section) {
 	MemoryLocation location;
 
@@ -347,9 +336,8 @@ static constexpr uint8_t ALIGN_CONSTRAINED = 1 << 0;
 // clang-format on
 static std::deque<Section *> unassignedSections[1 << 3];
 
-// Categorize a section depending on how constrained it is
+// Categorize a section depending on how constrained it is.
-// This is so the most-constrained sections are placed first
+// This is so the most-constrained sections are placed first.
-// @param section The section to categorize
 static void categorizeSection(Section &section) {
 	uint8_t constraints = 0;
 

src/link/object.cpp

@@ -41,9 +41,7 @@ static std::vector<std::vector<FileStackNode>> nodes;
 		var = static_cast<vartype>(tmpVal); \
 	} while (0)
 
-// Reads an unsigned long (32-bit) value from a file.
+// Reads an unsigned long (32-bit) value from a file, or `INT64_MAX` on failure.
-// @param file The file to read from. This will read 4 bytes from the file.
-// @return The value read, cast to a int64_t, or `INT64_MAX` on failure.
 static int64_t readLong(FILE *file) {
 	uint32_t value = 0;
 
@@ -65,31 +63,14 @@ static int64_t readLong(FILE *file) {
 	return value;
 }
 
-// Helper macro for reading longs from a file, and errors out if it fails to.
+// Helper macro to read a long from a file to a var, or error out if it fails to.
-// Not as a function to avoid overhead in the general case.
-// @param var The variable to stash the number into
-// @param file The file to read from. Its position will be advanced
-// @param ... A format string and related arguments; note that an extra string
-//            argument is provided, the reason for failure
 #define tryReadLong(var, file, ...) \
 	tryRead(readLong, int64_t, INT64_MAX, long, var, file, __VA_ARGS__)
 
-// There is no `readByte`, just use `fgetc` or `getc`.
+// Helper macro to read a byte from a file to a var, or error out if it fails to.
-
-// Helper macro for reading bytes from a file, and errors out if it fails to.
-// Not as a function to avoid overhead in the general case.
-// @param var The variable to stash the number into
-// @param file The file to read from. Its position will be advanced
-// @param ... A format string and related arguments; note that an extra string
-//            argument is provided, the reason for failure
 #define tryGetc(type, var, file, ...) tryRead(getc, int, EOF, type, var, file, __VA_ARGS__)
 
-// Helper macro for readings '\0'-terminated strings from a file, and errors out if it fails to.
+// Helper macro to read a '\0'-terminated string from a file, or error out if it fails to.
-// Not as a function to avoid overhead in the general case.
-// @param var The variable to stash the string into
-// @param file The file to read from. Its position will be advanced
-// @param ... A format string and related arguments; note that an extra string
-//            argument is provided, the reason for failure
 #define tryReadString(var, file, ...) \
 	do { \
 		FILE *tmpFile = file; \
@@ -105,21 +86,19 @@ static int64_t readLong(FILE *file) {
 
 // Functions to parse object files
 
-// Reads a file stack node form a file.
+// Reads a file stack node from a file.
-// @param file The file to read from
-// @param nodes The file's array of nodes
-// @param i The ID of the node in the array
-// @param fileName The filename to report in errors
 static void readFileStackNode(
-    FILE *file, std::vector<FileStackNode> &fileNodes, uint32_t i, char const *fileName
+    FILE *file, std::vector<FileStackNode> &fileNodes, uint32_t nodeID, char const *fileName
 ) {
-	FileStackNode &node = fileNodes[i];
+	FileStackNode &node = fileNodes[nodeID];
 	uint32_t parentID;
 
-	tryReadLong(parentID, file, "%s: Cannot read node #%" PRIu32 "'s parent ID: %s", fileName, i);
+	tryReadLong(
+	    parentID, file, "%s: Cannot read node #%" PRIu32 "'s parent ID: %s", fileName, nodeID
+	);
 	node.parent = parentID != UINT32_MAX ? &fileNodes[parentID] : nullptr;
 	tryReadLong(
-	    node.lineNo, file, "%s: Cannot read node #%" PRIu32 "'s line number: %s", fileName, i
+	    node.lineNo, file, "%s: Cannot read node #%" PRIu32 "'s line number: %s", fileName, nodeID
 	);
 	tryGetc(
 	    FileStackNodeType,
@@ -127,29 +106,31 @@ static void readFileStackNode(
 	    file,
 	    "%s: Cannot read node #%" PRIu32 "'s type: %s",
 	    fileName,
-	    i
+	    nodeID
 	);
 	switch (node.type) {
 	case NODE_FILE:
 	case NODE_MACRO:
 		node.data = "";
 		tryReadString(
-		    node.name(), file, "%s: Cannot read node #%" PRIu32 "'s file name: %s", fileName, i
+		    node.name(), file, "%s: Cannot read node #%" PRIu32 "'s file name: %s", fileName, nodeID
 		);
 		break;
 
 		uint32_t depth;
 	case NODE_REPT:
-		tryReadLong(depth, file, "%s: Cannot read node #%" PRIu32 "'s rept depth: %s", fileName, i);
-		node.data = std::vector<uint32_t>(depth);
-		for (uint32_t k = 0; k < depth; k++) {
 		tryReadLong(
-			    node.iters()[k],
+		    depth, file, "%s: Cannot read node #%" PRIu32 "'s rept depth: %s", fileName, nodeID
+		);
+		node.data = std::vector<uint32_t>(depth);
+		for (uint32_t i = 0; i < depth; i++) {
+			tryReadLong(
+			    node.iters()[i],
 			    file,
 			    "%s: Cannot read node #%" PRIu32 "'s iter #%" PRIu32 ": %s",
 			    fileName,
-			    i,
+			    nodeID,
-			    k
+			    i
 			);
 		}
 		if (!node.parent) {
@@ -158,16 +139,13 @@ static void readFileStackNode(
 			    0,
 			    "%s is not a valid object file: root node (#%" PRIu32 ") may not be REPT",
 			    fileName,
-			    i
+			    nodeID
 			);
 		}
 	}
 }
 
 // Reads a symbol from a file.
-// @param file The file to read from
-// @param symbol The symbol to fill
-// @param fileName The filename to report in errors
 static void readSymbol(
     FILE *file, Symbol &symbol, char const *fileName, std::vector<FileStackNode> const &fileNodes
 ) {
@@ -221,16 +199,12 @@ static void readSymbol(
 }
 
 // Reads a patch from a file.
-// @param file The file to read from
-// @param patch The patch to fill
-// @param fileName The filename to report in errors
-// @param i The number of the patch to report in errors
 static void readPatch(
     FILE *file,
     Patch &patch,
     char const *fileName,
     std::string const &sectName,
-    uint32_t i,
+    uint32_t patchID,
     std::vector<FileStackNode> const &fileNodes
 ) {
 	uint32_t nodeID, rpnSize;
@@ -242,7 +216,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s node ID: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	patch.src = &fileNodes[nodeID];
 	tryReadLong(
@@ -251,7 +225,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s line number: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	tryReadLong(
 	    patch.offset,
@@ -259,7 +233,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s offset: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	tryReadLong(
 	    patch.pcSectionID,
@@ -267,7 +241,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s PC offset: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	tryReadLong(
 	    patch.pcOffset,
@@ -275,7 +249,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s PC offset: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	tryGetc(
 	    PatchType,
@@ -284,7 +258,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s type: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 	patch.type = type;
 	tryReadLong(
@@ -293,7 +267,7 @@ static void readPatch(
 	    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s RPN size: %s",
 	    fileName,
 	    sectName.c_str(),
-	    i
+	    patchID
 	);
 
 	patch.rpnExpression.resize(rpnSize);
@@ -304,14 +278,13 @@ static void readPatch(
 		    "%s: Cannot read \"%s\"'s patch #%" PRIu32 "'s RPN expression: %s",
 		    fileName,
 		    sectName.c_str(),
-		    i,
+		    patchID,
 		    feof(file) ? "Unexpected end of file" : strerror(errno)
 		);
 	}
 }
 
-// Sets a patch's pcSection from its pcSectionID.
+// Sets a patch's `pcSection` from its `pcSectionID`.
-// @param patch The patch to fix
 static void
     linkPatchToPCSect(Patch &patch, std::vector<std::unique_ptr<Section>> const &fileSections) {
 	patch.pcSection =
@@ -319,9 +292,6 @@ static void
 }
 
 // Reads a section from a file.
-// @param file The file to read from
-// @param section The section to fill
-// @param fileName The filename to report in errors
 static void readSection(
     FILE *file, Section &section, char const *fileName, std::vector<FileStackNode> const &fileNodes
 ) {
@@ -432,8 +402,6 @@ static void readSection(
 }
 
 // Links a symbol to a section, keeping the section's symbol list sorted.
-// @param symbol The symbol to link
-// @param section The section to link
 static void linkSymToSect(Symbol &symbol, Section &section) {
 	uint32_t a = 0, b = section.symbols.size();
 	int32_t symbolOffset = symbol.label().offset;
@@ -452,20 +420,17 @@ static void linkSymToSect(Symbol &symbol, Section &section) {
 	section.symbols.insert(section.symbols.begin() + a, &symbol);
 }
 
-// Reads an assertion from a file
+// Reads an assertion from a file.
-// @param file The file to read from
-// @param assert The assertion to fill
-// @param fileName The filename to report in errors
 static void readAssertion(
     FILE *file,
     Assertion &assert,
     char const *fileName,
-    uint32_t i,
+    uint32_t assertID,
     std::vector<FileStackNode> const &fileNodes
 ) {
 	std::string assertName("Assertion #");
 
-	assertName += std::to_string(i);
+	assertName += std::to_string(assertID);
 	readPatch(file, assert.patch, fileName, assertName, 0, fileNodes);
 	tryReadString(assert.message, file, "%s: Cannot read assertion's message: %s", fileName);
 }

src/link/output.cpp

@@ -103,7 +103,7 @@ Section const *out_OverlappingSection(Section const &section) {
 }
 
 // Performs sanity checks on the overlay file.
-// @return The number of ROM banks in the overlay file
+// Returns the number of ROM banks in the overlay file.
 static uint32_t checkOverlaySize() {
 	if (!overlayFile) {
 		return 0;
@@ -133,7 +133,6 @@ static uint32_t checkOverlaySize() {
 // Expand `sections[SECTTYPE_ROMX]` to cover all the overlay banks.
 // This ensures that `writeROM` will output each bank, even if some are not
 // covered by any sections.
-// @param nbOverlayBanks The number of banks in the overlay file
 static void coverOverlayBanks(uint32_t nbOverlayBanks) {
 	// 2 if is32kMode, 1 otherwise
 	uint32_t nbRom0Banks = sectionTypeInfo[SECTTYPE_ROM0].size / BANK_SIZE;
@@ -165,10 +164,7 @@ static uint8_t getNextFillByte() {
 	return padValue;
 }
 
-// Write a ROM bank's sections to the output file.
+// Write a ROM bank's sections, ordered by increasing address, to the output file.
-// @param bankSections The bank's sections, ordered by increasing address
-// @param baseOffset The address of the bank's first byte in GB address space
-// @param size The size of the bank
 static void
     writeBank(std::deque<Section const *> *bankSections, uint16_t baseOffset, uint16_t size) {
 	uint16_t offset = 0;
@@ -340,7 +336,6 @@ static bool compareSymbols(SortedSymbol const &sym1, SortedSymbol const &sym2) {
 }
 
 // Write a bank's contents to the sym file
-// @param bankSections The bank's sections
 static void writeSymBank(SortedSections const &bankSections, SectionType type, uint32_t bank) {
 #define forEachSortedSection(sect, ...) \
 	do { \

src/link/patch.cpp

@@ -67,11 +67,6 @@ static Symbol const *getSymbol(std::vector<Symbol> const &symbolList, uint32_t i
 }
 
 // Compute a patch's value from its RPN string.
-// @param patch The patch to compute the value of
-// @param section The section the patch is contained in
-// @return The patch's value
-// @return isError Set if an error occurred during evaluation, and further
-//                 errors caused by the value should be suppressed.
 static int32_t computeRPNExpr(Patch const &patch, std::vector<Symbol> const &fileSymbols) {
 	uint8_t const *expression = patch.rpnExpression.data();
 	int32_t size = static_cast<int32_t>(patch.rpnExpression.size());
@@ -476,9 +471,7 @@ void patch_CheckAssertions() {
 	}
 }
 
-// Applies all of a section's patches
+// Applies all of a section's patches to a data section
-// @param section The section component to patch
-// @param dataSection The section to patch
 static void applyFilePatches(Section &section, Section &dataSection) {
 	verbosePrint("Patching section \"%s\"...\n", section.name.c_str());
 	for (Patch &patch : section.patches) {
@@ -543,7 +536,6 @@ static void applyFilePatches(Section &section, Section &dataSection) {
 }
 
 // Applies all of a section's patches, iterating over "components" of unionized sections
-// @param section The section to patch
 static void applyPatches(Section &section) {
 	if (!sect_HasData(section.type)) {
 		return;