diff --git a/include/link/object.hpp b/include/link/object.hpp index 1bb9270f8..ed642cb68 100644 --- a/include/link/object.hpp +++ b/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 diff --git a/include/link/output.hpp b/include/link/output.hpp index e456632e2..0f4436b00 100644 --- a/include/link/output.hpp +++ b/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 §ion); // 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 §ion); // Writes all output (bin, sym, map) files. diff --git a/include/link/patch.hpp b/include/link/patch.hpp index 240cfa5e3..8f9ac48e6 100644 --- a/include/link/patch.hpp +++ b/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 diff --git a/include/link/section.hpp b/include/link/section.hpp index b21f32d24..1872d9866 100644 --- a/include/link/section.hpp +++ b/include/link/section.hpp @@ -67,16 +67,12 @@ extern std::deque 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
&§ion); // 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 diff --git a/include/link/symbol.hpp b/include/link/symbol.hpp index 4335c3bbc..cf853fc29 100644 --- a/include/link/symbol.hpp +++ b/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); diff --git a/include/linkdefs.hpp b/include/linkdefs.hpp index 4ac52ab14..67b8d08e0 100644 --- a/include/linkdefs.hpp +++ b/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; } diff --git a/src/asm/rpn.cpp b/src/asm/rpn.cpp index 903002a68..9a7cb9063 100644 --- a/src/asm/rpn.cpp +++ b/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(); diff --git a/src/fix/main.cpp b/src/fix/main.cpp index ccdcaef52..070fc8851 100644 --- a/src/fix/main.cpp +++ b/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) { diff --git a/src/gfx/main.cpp b/src/gfx/main.cpp index c78983096..2498097bf 100644 --- a/src/gfx/main.cpp +++ b/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 readAtFile(std::string const &path, std::vector &argPool) { File file; if (!file.open(path, std::ios_base::in)) { diff --git a/src/gfx/pal_spec.cpp b/src/gfx/pal_spec.cpp index 4e2b3db91..515efd762 100644 --- a/src/gfx/pal_spec.cpp +++ b/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()); diff --git a/src/link/assign.cpp b/src/link/assign.cpp index b0220b527..ec3892bbb 100644 --- a/src/link/assign.cpp +++ b/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 §ion, 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 §ion, 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 §ion, 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 §ion, MemoryLocation &location) { SectionTypeInfo const &typeInfo = sectionTypeInfo[section.type]; @@ -214,9 +205,7 @@ static ssize_t getPlacement(Section const §ion, 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 §ion) { MemoryLocation location; @@ -347,9 +336,8 @@ static constexpr uint8_t ALIGN_CONSTRAINED = 1 << 0; // clang-format on static std::deque
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 §ion) { uint8_t constraints = 0; diff --git a/src/link/object.cpp b/src/link/object.cpp index 8f19035dd..ba805f90a 100644 --- a/src/link/object.cpp +++ b/src/link/object.cpp @@ -41,9 +41,7 @@ static std::vector> nodes; var = static_cast(tmpVal); \ } while (0) -// Reads an unsigned long (32-bit) value from a file. -// @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. +// Reads an unsigned long (32-bit) value from a file, 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. -// 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 +// Helper macro to read a long from a file to a var, or error out if it fails to. #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 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 +// Helper macro to read a byte from a file to a var, or error out if it fails to. #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. -// 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 +// Helper macro to read a '\0'-terminated string from a file, or error out if it fails to. #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. -// @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 +// Reads a file stack node from a file. static void readFileStackNode( - FILE *file, std::vector &fileNodes, uint32_t i, char const *fileName + FILE *file, std::vector &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); + tryReadLong( + depth, file, "%s: Cannot read node #%" PRIu32 "'s rept depth: %s", fileName, nodeID + ); node.data = std::vector(depth); - for (uint32_t k = 0; k < depth; k++) { + for (uint32_t i = 0; i < depth; i++) { tryReadLong( - node.iters()[k], + node.iters()[i], file, "%s: Cannot read node #%" PRIu32 "'s iter #%" PRIu32 ": %s", fileName, - i, - k + nodeID, + 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 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 §Name, - uint32_t i, + uint32_t patchID, std::vector 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. -// @param patch The patch to fix +// Sets a patch's `pcSection` from its `pcSectionID`. static void linkPatchToPCSect(Patch &patch, std::vector> 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 §ion, char const *fileName, std::vector 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 §ion) { uint32_t a = 0, b = section.symbols.size(); int32_t symbolOffset = symbol.label().offset; @@ -452,20 +420,17 @@ static void linkSymToSect(Symbol &symbol, Section §ion) { section.symbols.insert(section.symbols.begin() + a, &symbol); } -// 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 +// Reads an assertion from a file. static void readAssertion( FILE *file, Assertion &assert, char const *fileName, - uint32_t i, + uint32_t assertID, std::vector 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); } diff --git a/src/link/output.cpp b/src/link/output.cpp index 66f52389a..95126cc4d 100644 --- a/src/link/output.cpp +++ b/src/link/output.cpp @@ -103,7 +103,7 @@ Section const *out_OverlappingSection(Section const §ion) { } // 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. -// @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 +// Write a ROM bank's sections, ordered by increasing address, to the output file. static void writeBank(std::deque
*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 { \ diff --git a/src/link/patch.cpp b/src/link/patch.cpp index d47bbd105..839e2edf7 100644 --- a/src/link/patch.cpp +++ b/src/link/patch.cpp @@ -67,11 +67,6 @@ static Symbol const *getSymbol(std::vector 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 const &fileSymbols) { uint8_t const *expression = patch.rpnExpression.data(); int32_t size = static_cast(patch.rpnExpression.size()); @@ -476,9 +471,7 @@ void patch_CheckAssertions() { } } -// Applies all of a section's patches -// @param section The section component to patch -// @param dataSection The section to patch +// Applies all of a section's patches to a data section static void applyFilePatches(Section §ion, Section &dataSection) { verbosePrint("Patching section \"%s\"...\n", section.name.c_str()); for (Patch &patch : section.patches) { @@ -543,7 +536,6 @@ static void applyFilePatches(Section §ion, 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 §ion) { if (!sect_HasData(section.type)) { return;