Remove redundant @-style doc comment tags

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
-// @param i The ID of the file
-void obj_ReadFile(char const *fileName, unsigned int i);
+void obj_ReadFile(char const *fileName, unsigned int fileID);
 
 // 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
-// @return The address of the last byte in that memory region
+// Returns a memory region's end address (last byte), e.g. 0x7FFF
 static inline uint16_t endaddr(SectionType type) {
 	return sectionTypeInfo[type].startAddr + sectionTypeInfo[type].size - 1;
 }
 
-// Computes a memory region's number of banks
-// @return The number of banks, 1 for regions without banking
+// Returns a memory region's number of banks, or 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
-// @param argPool Argument characters will be appended to this vector, for storage purposes.
+// Turn an at-file's contents into an argv that `getopt` can handle, appending them to `argPool`.
 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`.
-// @return true if a line was read.
+// Appends the first line read from `file` to the end of the provided `buffer`.
+// 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.
-// @param section The section to be placed
-// @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
+// Returns a suitable free space index into `memory[section->type]` at which to place the given
+// section, 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
-//          sections of decreasing size.
-// @param section The section to place
+// Due to the implemented algorithm, this should be called with sections of decreasing size!
 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
-// This is so the most-constrained sections are placed first
-// @param section The section to categorize
+// Categorize a section depending on how constrained it is.
+// This is so the most-constrained sections are placed first.
 static void categorizeSection(Section &section) {
 	uint8_t constraints = 0;