gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 18:22:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Rangi
2025-01-29 19:56:28 -05:00
committed by GitHub
parent e20347e38c
commit b35e9d86fb
14 changed files with 50 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
include/link/object.hpp
View File

@@ -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

3
include/link/output.hpp
View File

@@ -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.

1
include/link/patch.hpp
View File

@@ -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

4
include/link/section.hpp
View File

@@ -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

2
include/link/symbol.hpp
View File

@@ -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);

8
include/linkdefs.hpp
View File

@@ -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;
}

6
src/asm/rpn.cpp
View File

@@ -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();

14
src/fix/main.cpp
View File

@@ -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) {

3
src/gfx/main.cpp
View File

@@ -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)) {

4
src/gfx/pal_spec.cpp
View File

@@ -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());

22
src/link/assign.cpp
View File

@@ -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;

103
src/link/object.cpp
View File

@@ -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.
// @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<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);
tryReadLong(
depth, file, "%s: Cannot read node #%" PRIu32 "'s rept depth: %s", fileName, nodeID
);
node.data = std::vector<uint32_t>(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<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.
// @param patch The patch to fix
// Sets a patch's `pcSection` from its `pcSectionID`.
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
// @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<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);
}

9
src/link/output.cpp
View File

@@ -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.
// @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<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 { \

10
src/link/patch.cpp
View File

@@ -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
// @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 &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;