Use // line comments not /* block comments

include/asm/charmap.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_CHARMAP_HPP
 #define RGBDS_ASM_CHARMAP_HPP

include/asm/fixpoint.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_FIXPOINT_HPP
 #define RGBDS_ASM_FIXPOINT_HPP

include/asm/format.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_FORMAT_HPP
 #define RGBDS_ASM_FORMAT_HPP

include/asm/fstack.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 // Contains some assembler-wide defines and externs
 

include/asm/lexer.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_LEXER_HPP
 #define RGBDS_ASM_LEXER_HPP

include/asm/macro.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_MACRO_HPP
 #define RGBDS_ASM_MACRO_HPP

include/asm/main.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_MAIN_HPP
 #define RGBDS_ASM_MAIN_HPP

include/asm/opt.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_OPT_HPP
 #define RGBDS_ASM_OPT_HPP

include/asm/output.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_OUTPUT_HPP
 #define RGBDS_ASM_OUTPUT_HPP

include/asm/rpn.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_RPN_HPP
 #define RGBDS_ASM_RPN_HPP

include/asm/section.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_SECTION_HPP
 #define RGBDS_ASM_SECTION_HPP

include/asm/symbol.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_SYMBOL_HPP
 #define RGBDS_ASM_SYMBOL_HPP

include/asm/warning.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ASM_WARNING_HPP
 #define RGBDS_ASM_WARNING_HPP
@@ -62,27 +62,21 @@ extern bool warningsAreErrors;
 
 void processWarningFlag(char const *flag);
 
-/*
+// Used to warn the user about problems that don't prevent the generation of
- * Used to warn the user about problems that don't prevent the generation of
+// valid code.
- * valid code.
- */
 [[gnu::format(printf, 2, 3)]] void warning(WarningID id, char const *fmt, ...);
 
-/*
+// Used for errors that compromise the whole assembly process by affecting the
- * Used for errors that compromise the whole assembly process by affecting the
+// following code, potencially making the assembler generate errors caused by
- * following code, potencially making the assembler generate errors caused by
+// the first one and unrelated to the code that the assembler complains about.
- * the first one and unrelated to the code that the assembler complains about.
+// It is also used when the assembler goes into an invalid state (for example,
- * It is also used when the assembler goes into an invalid state (for example,
+// when it fails to allocate memory).
- * when it fails to allocate memory).
- */
 [[gnu::format(printf, 1, 2), noreturn]] void fatalerror(char const *fmt, ...);
 
-/*
+// Used for errors that make it impossible to assemble correctly, but don't
- * Used for errors that make it impossible to assemble correctly, but don't
+// affect the following code. The code will fail to assemble but the user will
- * affect the following code. The code will fail to assemble but the user will
+// get a list of all errors at the end, making it easier to fix all of them at
- * get a list of all errors at the end, making it easier to fix all of them at
+// once.
- * once.
- */
 [[gnu::format(printf, 1, 2)]] void error(char const *fmt, ...);
 
 #endif // RGBDS_ASM_WARNING_HPP

include/defaultinitvec.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_DEFAULT_INIT_ALLOC_HPP
 #define RGBDS_DEFAULT_INIT_ALLOC_HPP
@@ -6,14 +6,11 @@
 #include <memory>
 #include <vector>
 
-/*
+// Allocator adaptor that interposes construct() calls to convert value-initialization
- * Allocator adaptor that interposes construct() calls to convert value-initialization
+// (which is what you get with e.g. `vector::resize`) into default-initialization (which does not
- * (which is what you get with e.g. `vector::resize`) into default-initialization (which does not
+// zero out non-class types).
- * zero out non-class types).
+// From
- * From
+// https://stackoverflow.com/questions/21028299/is-this-behavior-of-vectorresizesize-type-n-under-c11-and-boost-container/21028912#21028912
- * https://stackoverflow.com/questions/21028299/is-this-behavior-of-vectorresizesize-type-n-under-c11-and-boost-container/21028912#21028912
- */
-
 template<typename T, typename A = std::allocator<T>>
 class default_init_allocator : public A {
 	using a_t = std::allocator_traits<A>;

include/either.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_EITHER_HPP
 #define RGBDS_EITHER_HPP

include/error.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ERROR_HPP
 #define RGBDS_ERROR_HPP

include/extern/getopt.hpp

@@ -1,6 +1,6 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
-/* This implementation was taken from musl and modified for RGBDS */
+// This implementation was taken from musl and modified for RGBDS
 
 #ifndef RGBDS_EXTERN_GETOPT_HPP
 #define RGBDS_EXTERN_GETOPT_HPP

include/extern/utf8decoder.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_EXTERN_UTF8DECODER_HPP
 #define RGBDS_EXTERN_UTF8DECODER_HPP

include/file.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_FILE_HPP
 #define RGBDS_FILE_HPP
@@ -25,10 +25,8 @@ public:
 	File() {}
 	~File() { close(); }
 
-	/**
+	// This should only be called once, and before doing any `->` operations.
-	 * This should only be called once, and before doing any `->` operations.
+	// Returns `nullptr` on error, and a non-null pointer otherwise.
-	 * Returns `nullptr` on error, and a non-null pointer otherwise.
-	 */
 	File *open(std::string const &path, std::ios_base::openmode mode) {
 		if (path != "-") {
 			_file.emplace<std::filebuf>();

include/gfx/main.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_MAIN_HPP
 #define RGBDS_GFX_MAIN_HPP
@@ -65,31 +65,19 @@ struct Options {
 
 extern Options options;
 
-/*
+// Prints the error count, and exits with failure
- * Prints the error count, and exits with failure
- */
 [[noreturn]] void giveUp();
-/*
+// If any error has been emitted thus far, calls `giveUp()`.
- * If any error has been emitted thus far, calls `giveUp()`.
- */
 void requireZeroErrors();
-/*
+// Prints a warning, and does not change the error count
- * Prints a warning, and does not change the error count
- */
 [[gnu::format(printf, 1, 2)]] void warning(char const *fmt, ...);
-/*
+// Prints an error, and increments the error count
- * Prints an error, and increments the error count
- */
 [[gnu::format(printf, 1, 2)]] void error(char const *fmt, ...);
-/*
+// Prints an error, and increments the error count
- * Prints an error, and increments the error count
+// Does not take format arguments so `format_` and `-Wformat-security` won't complain about
- * Does not take format arguments so `format_` and `-Wformat-security` won't complain about
+// calling `errorMessage(msg)`.
- * calling `errorMessage(msg)`.
- */
 void errorMessage(char const *msg);
-/*
+// Prints a fatal error, increments the error count, and gives up
- * Prints a fatal error, increments the error count, and gives up
- */
 [[gnu::format(printf, 1, 2), noreturn]] void fatal(char const *fmt, ...);
 
 struct Palette {

include/gfx/pal_packing.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_PAL_PACKING_HPP
 #define RGBDS_GFX_PAL_PACKING_HPP
@@ -11,9 +11,7 @@
 struct Palette;
 class ProtoPalette;
 
-/*
+// Returns which palette each proto-palette maps to, and how many palettes are necessary
- * Returns which palette each proto-palette maps to, and how many palettes are necessary
- */
 std::tuple<DefaultInitVec<size_t>, size_t>
     overloadAndRemove(std::vector<ProtoPalette> const &protoPalettes);
 

include/gfx/pal_sorting.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_PAL_SORTING_HPP
 #define RGBDS_GFX_PAL_SORTING_HPP

include/gfx/pal_spec.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_PAL_SPEC_HPP
 #define RGBDS_GFX_PAL_SPEC_HPP

include/gfx/process.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_PROCESS_HPP
 #define RGBDS_GFX_PROCESS_HPP

include/gfx/proto_palette.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_PROTO_PALETTE_HPP
 #define RGBDS_GFX_PROTO_PALETTE_HPP

include/gfx/reverse.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_REVERSE_HPP
 #define RGBDS_GFX_REVERSE_HPP

include/gfx/rgba.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_GFX_RGBA_HPP
 #define RGBDS_GFX_RGBA_HPP
@@ -13,9 +13,7 @@ struct Rgba {
 
 	constexpr Rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a)
 	    : red(r), green(g), blue(b), alpha(a) {}
-	/*
+	// Constructs the color from a "packed" RGBA representation (0xRRGGBBAA)
-	 * Constructs the color from a "packed" RGBA representation (0xRRGGBBAA)
-	 */
 	explicit constexpr Rgba(uint32_t rgba = 0)
 	    : red(rgba >> 24), green(rgba >> 16), blue(rgba >> 8), alpha(rgba) {}
 
@@ -32,10 +30,8 @@ struct Rgba {
 		};
 	}
 
-	/*
+	// Returns this RGBA as a 32-bit number that can be printed in hex (`%08x`) to yield its CSS
-	 * Returns this RGBA as a 32-bit number that can be printed in hex (`%08x`) to yield its CSS
+	// representation
-	 * representation
-	 */
 	uint32_t toCSS() const {
 		auto shl = [](uint8_t val, unsigned shift) { return static_cast<uint32_t>(val) << shift; };
 		return shl(red, 24) | shl(green, 16) | shl(blue, 8) | shl(alpha, 0);
@@ -43,19 +39,15 @@ struct Rgba {
 	bool operator==(Rgba const &rhs) const { return toCSS() == rhs.toCSS(); }
 	bool operator!=(Rgba const &rhs) const { return toCSS() != rhs.toCSS(); }
 
-	/*
+	// CGB colors are RGB555, so we use bit 15 to signify that the color is transparent instead
-	 * CGB colors are RGB555, so we use bit 15 to signify that the color is transparent instead
+	// Since the rest of the bits don't matter then, we return 0x8000 exactly.
-	 * Since the rest of the bits don't matter then, we return 0x8000 exactly.
-	 */
 	static constexpr uint16_t transparent = 0b1'00000'00000'00000;
 
 	static constexpr uint8_t transparency_threshold = 0x10;
 	bool isTransparent() const { return alpha < transparency_threshold; }
 	static constexpr uint8_t opacity_threshold = 0xF0;
 	bool isOpaque() const { return alpha >= opacity_threshold; }
-	/*
+	// Computes the equivalent CGB color, respects the color curve depending on options
-	 * Computes the equivalent CGB color, respects the color curve depending on options
-	 */
 	uint16_t cgbColor() const;
 
 	bool isGray() const { return red == green && green == blue; }

include/helpers.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_HELPERS_HPP
 #define RGBDS_HELPERS_HPP

include/itertools.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_ITERTOOLS_HPP
 #define RGBDS_ITERTOOLS_HPP

include/link/assign.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_ASSIGN_HPP
 #define RGBDS_LINK_ASSIGN_HPP

include/link/main.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_MAIN_HPP
 #define RGBDS_LINK_MAIN_HPP

include/link/object.hpp

@@ -1,19 +1,15 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_OBJECT_HPP
 #define RGBDS_LINK_OBJECT_HPP
 
-/*
+// Read an object (.o) file, and add its info to the data structures.
- * 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 fileName A path to the object file to be read
+// @param i The ID of the file
- * @param i The ID of the file
- */
 void obj_ReadFile(char const *fileName, unsigned int i);
 
-/*
+// Sets up object file reading
- * Sets up object file reading
+// @param nbFiles The number of object files that will be read
- * @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

@@ -1,26 +1,20 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_OUTPUT_HPP
 #define RGBDS_LINK_OUTPUT_HPP
 
 struct Section;
 
-/*
+// Registers a section for output.
- * Registers a section for output.
+// @param section The section to add
- * @param section The section to add
- */
 void out_AddSection(Section const &section);
 
-/*
+// Finds an assigned section overlapping another one.
- * Finds an assigned section overlapping another one.
+// @param section The section that is being overlapped
- * @param section The section that is being overlapped
+// @return A section overlapping it
- * @return A section overlapping it
- */
 Section const *out_OverlappingSection(Section const &section);
 
-/*
+// Writes all output (bin, sym, map) files.
- * Writes all output (bin, sym, map) files.
- */
 void out_WriteFiles();
 
 #endif // RGBDS_LINK_OUTPUT_HPP

include/link/patch.hpp

@@ -1,17 +1,13 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_PATCH_HPP
 #define RGBDS_LINK_PATCH_HPP
 
-/*
+// Checks all assertions
- * Checks all assertions
+// @return true if assertion failed
- * @return true if assertion failed
- */
 void patch_CheckAssertions();
 
-/*
+// Applies all SECTIONs' patches to them
- * Applies all SECTIONs' patches to them
- */
 void patch_ApplyPatches();
 
 #endif // RGBDS_LINK_PATCH_HPP

include/link/sdas_obj.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_SDAS_OBJ_HPP
 #define RGBDS_LINK_SDAS_OBJ_HPP

include/link/section.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_SECTION_HPP
 #define RGBDS_LINK_SECTION_HPP
@@ -65,29 +65,21 @@ struct Assertion {
 
 extern std::deque<Assertion> assertions;
 
-/*
+// Execute a callback for each section currently registered.
- * Execute a callback for each section currently registered.
+// This is to avoid exposing the data structure in which sections are stored.
- * This is to avoid exposing the data structure in which sections are stored.
+// @param callback The function to call for each structure.
- * @param callback The function to call for each structure.
- */
 void sect_ForEach(void (*callback)(Section &));
 
-/*
+// Registers a section to be processed.
- * Registers a section to be processed.
+// @param section The section to register.
- * @param section The section to register.
- */
 void sect_AddSection(std::unique_ptr<Section> &&section);
 
-/*
+// Finds a section by its name.
- * Finds a section by its name.
+// @param name The name of the section to look for
- * @param name The name of the section to look for
+// @return A pointer to the section, or `nullptr` if it wasn't found
- * @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
- * Checks if all sections meet reasonable criteria, such as max size
- */
 void sect_DoSanityChecks();
 
 #endif // RGBDS_LINK_SECTION_HPP

include/link/symbol.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINK_SYMBOL_HPP
 #define RGBDS_LINK_SYMBOL_HPP
@@ -41,11 +41,9 @@ void sym_ForEach(void (*callback)(Symbol &));
 
 void sym_AddSymbol(Symbol &symbol);
 
-/*
+// Finds a symbol in all the defined symbols.
- * Finds a symbol in all the defined symbols.
+// @param name The name of the symbol to look for
- * @param name The name of the symbol to look for
+// @return A pointer to the symbol, or `nullptr` if not found.
- * @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

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_LINKDEFS_HPP
 #define RGBDS_LINKDEFS_HPP
@@ -92,29 +92,23 @@ extern struct SectionTypeInfo {
 	uint32_t lastBank;
 } sectionTypeInfo[SECTTYPE_INVALID];
 
-/*
+// Tells whether a section has data in its object file definition,
- * Tells whether a section has data in its object file definition,
+// depending on type.
- * depending on type.
+// @param type The section's type
- * @param type The section's type
+// @return `true` if the section's definition includes data
- * @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
- * Computes a memory region's end address (last byte), eg. 0x7FFF
+// @return The address of the last byte in that memory region
- * @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
- * Computes a memory region's number of banks
+// @return The number of banks, 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;
 }

include/opmath.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_OP_MATH_HPP
 #define RGBDS_OP_MATH_HPP

include/platform.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 // platform-specific hacks
 

include/util.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_UTIL_HPP
 #define RGBDS_UTIL_HPP
@@ -9,9 +9,7 @@
 
 char const *printChar(int c);
 
-/*
+// @return The number of bytes read, or 0 if invalid data was found
- * @return The number of bytes read, or 0 if invalid data was found
- */
 size_t readUTF8Char(std::vector<int32_t> *dest, char const *src);
 
 #endif // RGBDS_UTIL_HPP

include/version.hpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #ifndef RGBDS_VERSION_HPP
 #define RGBDS_VERSION_HPP

src/asm/charmap.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/charmap.hpp"
 

src/asm/fixpoint.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 // Fixed-point math routines
 

src/asm/format.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/format.hpp"
 

src/asm/fstack.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/fstack.hpp"
 #include <sys/stat.h>

src/asm/lexer.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/lexer.hpp"
 #include <sys/stat.h>

src/asm/macro.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/macro.hpp"
 

src/asm/main.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/main.hpp"
 
@@ -54,13 +54,12 @@ static char const *optstring = "b:D:Eg:hI:M:o:P:p:Q:r:s:VvW:wX:";
 static int depType; // Variants of `-M`
 
 // Equivalent long options
-// Please keep in the same order as short opts
+// Please keep in the same order as short opts.
-//
 // Also, make sure long opts don't create ambiguity:
 // A long opt's name should start with the same letter as its short opt,
 // except if it doesn't create any ambiguity (`verbose` versus `version`).
 // This is because long opt matching, even to a single char, is prioritized
-// over short opt matching
+// over short opt matching.
 static option const longopts[] = {
     {"binary-digits",   required_argument, nullptr,  'b'},
     {"define",          required_argument, nullptr,  'D'},

src/asm/opt.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include <ctype.h>
 #include <errno.h>

src/asm/output.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/output.hpp"
 

src/asm/parser.y

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 %language "c++"
 %define api.value.type variant

src/asm/rpn.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/rpn.hpp"
 
@@ -225,12 +225,9 @@ static bool tryConstLogNot(Expression const &expr) {
 	return knownBits != 0;
 }
 
-/*
+// Attempts to compute a constant LOW() from non-constant argument
- * Attempts to compute a constant LOW() from non-constant argument
+// This is possible if the argument is a symbol belonging to an `ALIGN[8]` section.
- * 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.
- *
- * @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())
@@ -251,13 +248,10 @@ static int32_t tryConstLow(Expression const &expr) {
 	return (symbolOfs + sect.alignOfs) & 0xFF;
 }
 
-/*
+// Attempts to compute a constant binary AND with one non-constant operands
- * Attempts to compute a constant binary AND with one non-constant operands
+// This is possible if one operand is a symbol belonging to an `ALIGN[N]` section, and the other is
- * 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.
- * 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.
- *
- * @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/asm/section.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/section.hpp"
 

src/asm/symbol.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/symbol.hpp"
 

src/asm/warning.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "asm/warning.hpp"
 

src/error.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "error.hpp"
 

src/extern/getopt.cpp

@@ -1,6 +1,6 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
-/* This implementation was taken from musl and modified for RGBDS */
+// This implementation was taken from musl and modified for RGBDS
 
 #include "extern/getopt.hpp"
 
@@ -57,7 +57,7 @@ static int getopt(int argc, char *argv[], char const *optstring) {
 	k = mbtowc(&c, argv[musl_optind] + musl_optpos, MB_LEN_MAX);
 	if (k < 0) {
 		k = 1;
-		c = 0xFFFD; /* replacement char */
+		c = 0xFFFD; // replacement char
 	}
 	optchar = argv[musl_optind] + musl_optpos;
 	musl_optpos += k;

src/extern/utf8decoder.cpp

@@ -1,35 +1,35 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
-/* UTF-8 decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ */
+// UTF-8 decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/
 
 #include "extern/utf8decoder.hpp"
 
 static uint8_t const utf8d[] = {
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 00..0f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 00..0f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 10..1f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 10..1f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 20..2f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 20..2f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 30..3f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 30..3f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 40..4f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 40..4f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 50..5f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 50..5f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 60..6f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 60..6f
-    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* 70..7f */
+    0,  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 70..7f
-    1,  1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, /* 80..8f */
+    1,  1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 80..8f
-    9,  9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, /* 90..9f */
+    9,  9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, // 90..9f
-    7,  7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, /* a0..af */
+    7,  7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, // a0..af
-    7,  7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, /* b0..bf */
+    7,  7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, // b0..bf
-    8,  8, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, /* c0..cf */
+    8,  8, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // c0..cf
-    2,  2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, /* d0..df */
+    2,  2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // d0..df
-    10, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4, 3, 3, /* e0..ef */
+    10, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4, 3, 3, // e0..ef
-    11, 6, 6, 6, 5, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, /* f0..ff */
+    11, 6, 6, 6, 5, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, // f0..ff
-    0,  1, 2, 3, 5, 8, 7, 1, 1, 1, 4, 6, 1, 1, 1, 1, /* s0 */
+    0,  1, 2, 3, 5, 8, 7, 1, 1, 1, 4, 6, 1, 1, 1, 1, // s0
-    1,  1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, /* s1 */
+    1,  1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // s1
-    1,  0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, /* s1 */
+    1,  0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, // s1
-    1,  2, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1, 1, /* s3 */
+    1,  2, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1, 1, // s3
-    1,  1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, /* s4 */
+    1,  1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, // s4
-    1,  2, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, /* s5 */
+    1,  2, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, // s5
-    1,  1, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, /* s6 */
+    1,  1, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, // s6
-    1,  3, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, /* s7 */
+    1,  3, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, // s7
-    1,  3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, /* s8 */
+    1,  3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // s8
 };
 
 uint32_t decode(uint32_t *state, uint32_t *codep, uint8_t byte) {

src/fix/main.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include <sys/stat.h>
 #include <sys/types.h>
@@ -25,16 +25,13 @@ static constexpr off_t BANK_SIZE = 0x4000;
 // Short options
 static char const *optstring = "Ccf:hi:jk:L:l:m:n:Op:r:st:Vv";
 
-/*
+// Equivalent long options
- * Equivalent long options
+// Please keep in the same order as short opts.
- * Please keep in the same order as short opts
+// Also, make sure long opts don't create ambiguity:
- *
+// A long opt's name should start with the same letter as its short opt,
- * Also, make sure long opts don't create ambiguity:
+// except if it doesn't create any ambiguity (`verbose` versus `version`).
- * A long opt's name should start with the same letter as its short opt,
+// This is because long opt matching, even to a single char, is prioritized
- * except if it doesn't create any ambiguity (`verbose` versus `version`).
+// over short opt matching.
- * This is because long opt matching, even to a single char, is prioritized
- * over short opt matching
- */
 static option const longopts[] = {
     {"color-only",       no_argument,       nullptr, 'C'},
     {"color-compatible", no_argument,       nullptr, 'c'},
@@ -186,9 +183,7 @@ static void printAcceptedMBCNames() {
 
 static uint8_t tpp1Rev[2];
 
-/*
+// @return False on failure
- * @return False on failure
- */
 static bool readMBCSlice(char const *&name, char const *expected) {
 	while (*expected) {
 		char c = *name++;
@@ -822,12 +817,10 @@ static ssize_t writeBytes(int fd, uint8_t *buf, size_t len) {
 	return total;
 }
 
-/*
+// @param rom0 A pointer to rom0
- * @param rom0 A pointer to rom0
+// @param addr What address to check
- * @param addr What address to check
+// @param fixedByte The fixed byte at the address
- * @param fixedByte The fixed byte at the address
+// @param areaName Name to be displayed in the warning message
- * @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];
 
@@ -837,13 +830,11 @@ static void overwriteByte(uint8_t *rom0, uint16_t addr, uint8_t fixedByte, char
 	rom0[addr] = fixedByte;
 }
 
-/*
+// @param rom0 A pointer to rom0
- * @param rom0 A pointer to rom0
+// @param startAddr What address to begin checking from
- * @param startAddr What address to begin checking from
+// @param fixed The fixed bytes at the address
- * @param fixed The fixed bytes at the address
+// @param size How many bytes to check
- * @param size How many bytes to check
+// @param areaName Name to be displayed in the warning message
- * @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
 ) {
@@ -861,12 +852,10 @@ static void overwriteBytes(
 	memcpy(&rom0[startAddr], fixed, size);
 }
 
-/*
+// @param input File descriptor to be used for reading
- * @param input File descriptor to be used for reading
+// @param output File descriptor to be used for writing, may be equal to `input`
- * @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 name The file's name, to be displayed for error output
+// @param fileSize The file's size if known, 0 if not.
- * @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

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/main.hpp"
 
@@ -110,16 +110,13 @@ void Options::verbosePrint(uint8_t level, char const *fmt, ...) const {
 // Short options
 static char const *optstring = "-Aa:b:Cc:d:hi:L:mN:n:Oo:Pp:Qq:r:s:Tt:U:uVvXx:YZ";
 
-/*
+// Equivalent long options
- * Equivalent long options
+// Please keep in the same order as short opts.
- * Please keep in the same order as short opts
+// Also, make sure long opts don't create ambiguity:
- *
+// A long opt's name should start with the same letter as its short opt,
- * Also, make sure long opts don't create ambiguity:
+// except if it doesn't create any ambiguity (`verbose` versus `version`).
- * A long opt's name should start with the same letter as its short opt,
+// This is because long opt matching, even to a single char, is prioritized
- * except if it doesn't create any ambiguity (`verbose` versus `version`).
+// over short opt matching.
- * This is because long opt matching, even to a single char, is prioritized
- * over short opt matching
- */
 static option const longopts[] = {
     {"auto-attr-map",    no_argument,       nullptr, 'A'},
     {"attr-map",         required_argument, nullptr, 'a'},
@@ -173,10 +170,8 @@ static void printUsage() {
 	);
 }
 
-/*
+// Parses a number at the beginning of a string, moving the pointer to skip the parsed characters.
- * Parses a number at the beginning of a string, moving the pointer to skip the parsed characters
+// Returns the provided errVal on error.
- * Returns the provided errVal on error
- */
 static uint16_t parseNumber(char *&string, char const *errPrefix, uint16_t errVal = UINT16_MAX) {
 	uint8_t base = 10;
 	if (*string == '\0') {
@@ -199,12 +194,10 @@ static uint16_t parseNumber(char *&string, char const *errPrefix, uint16_t errVa
 		}
 	}
 
-	/*
+	// Turns a digit into its numeric value in the current base, if it has one.
-	 * Turns a digit into its numeric value in the current base, if it has one.
+	// Maximum is inclusive. The string_view is modified to "consume" all digits.
-	 * Maximum is inclusive. The string_view is modified to "consume" all digits.
+	// Returns 255 on parse failure (including wrong char for base), in which case
-	 * Returns 255 on parse failure (including wrong char for base), in which case
+	// the string_view may be pointing on garbage.
-	 * the string_view may be pointing on garbage.
-	 */
 	auto charIndex = [&base](unsigned char c) -> uint8_t {
 		unsigned char index = c - '0'; // Use wrapping semantics
 		if (base == 2 && index >= 2) {
@@ -272,10 +265,8 @@ 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
+// @param argPool Argument characters will be appended to this vector, for storage purposes.
- * @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)) {
@@ -347,13 +338,10 @@ static std::vector<size_t> readAtFile(std::string const &path, std::vector<char>
 	}
 }
 
-/*
+// Parses an arg vector, modifying `options` and `localOptions` as options are read.
- * Parses an arg vector, modifying `options` and `localOptions` as options are read.
+// The `localOptions` struct is for flags which must be processed after the option parsing finishes.
- * The `localOptions` struct is for flags which must be processed after the option parsing finishes.
+// Returns `nullptr` if the vector was fully parsed, or a pointer (which is part of the arg vector)
- *
+// to an "at-file" path if one is encountered.
- * Returns `nullptr` if the vector was fully parsed, or a pointer (which is part of the arg vector)
- * to an "at-file" path if one is encountered.
- */
 static char *parseArgv(int argc, char *argv[]) {
 	for (int ch; (ch = musl_getopt_long_only(argc, argv, optstring, longopts, nullptr)) != -1;) {
 		char *arg = musl_optarg; // Make a copy for scanning
@@ -887,9 +875,7 @@ void Palette::addColor(uint16_t color) {
 	}
 }
 
-/*
+// Returns the ID of the color in the palette, or `size()` if the color is not in
- * Returns the ID of the color in the palette, or `size()` if the color is not in
- */
 uint8_t Palette::indexOf(uint16_t color) const {
 	return color == Rgba::transparent
 	           ? 0

src/gfx/pal_packing.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/pal_packing.hpp"
 
@@ -27,15 +27,11 @@
 //  Tile | Proto-palette
 //  Page | Palette
 
-/*
+// A reference to a proto-palette, and attached attributes for sorting purposes
- * A reference to a proto-palette, and attached attributes for sorting purposes
- */
 struct ProtoPalAttrs {
 	size_t protoPalIndex;
-	/*
+	// Pages from which we are banned (to prevent infinite loops)
-	 * Pages from which we are banned (to prevent infinite loops)
+	// This is dynamic because we wish not to hard-cap the amount of palettes
-	 * This is dynamic because we wish not to hard-cap the amount of palettes
-	 */
 	std::vector<bool> bannedPages;
 
 	explicit ProtoPalAttrs(size_t index) : protoPalIndex(index) {}
@@ -50,10 +46,8 @@ struct ProtoPalAttrs {
 	}
 };
 
-/*
+// A collection of proto-palettes assigned to a palette
- * A collection of proto-palettes assigned to a palette
+// Does not contain the actual color indices because we need to be able to remove elements
- * Does not contain the actual color indices because we need to be able to remove elements
- */
 class AssignedProtos {
 	// We leave room for emptied slots to avoid copying the structs around on removal
 	std::vector<std::optional<ProtoPalAttrs>> _assigned;
@@ -127,10 +121,8 @@ public:
 	}
 	const_iterator end() const { return const_iterator{&_assigned, _assigned.end()}; }
 
-	/*
+	// Assigns a new ProtoPalAttrs in a free slot, assuming there is one
-	 * Assigns a new ProtoPalAttrs in a free slot, assuming there is one
+	// Args are passed to the `ProtoPalAttrs`'s constructor
-	 * Args are passed to the `ProtoPalAttrs`'s constructor
-	 */
 	template<typename... Ts>
 	void assign(Ts &&...args) {
 		auto freeSlot =
@@ -192,9 +184,7 @@ private:
 		return colors;
 	}
 public:
-	/*
+	// Returns the number of distinct colors
-	 * Returns the number of distinct colors
-	 */
 	size_t volume() const { return uniqueColors().size(); }
 	bool canFit(ProtoPalette const &protoPal) const {
 		auto &colors = uniqueColors();
@@ -218,10 +208,8 @@ public:
 		return factor;
 	}();
 
-	/*
+	// Computes the "relative size" of a proto-palette on this palette;
-	 * Computes the "relative size" of a proto-palette on this palette;
+	// it's a measure of how much this proto-palette would "cost" to introduce.
-	 * it's a measure of how much this proto-palette would "cost" to introduce.
-	 */
 	uint32_t relSizeOf(ProtoPalette const &protoPal) const {
 		// NOTE: this function must not call `uniqueColors`, or one of its callers will break!
 
@@ -244,9 +232,7 @@ public:
 		return relSize;
 	}
 
-	/*
+	// Computes the "relative size" of a set of proto-palettes on this palette
-	 * Computes the "relative size" of a set of proto-palettes on this palette
-	 */
 	template<typename Iter>
 	auto combinedVolume(Iter &&begin, Iter const &end, std::vector<ProtoPalette> const &protoPals)
 	    const {
@@ -254,9 +240,7 @@ public:
 		addUniqueColors(colors, std::forward<Iter>(begin), end, protoPals);
 		return colors.size();
 	}
-	/*
+	// Computes the "relative size" of a set of colors on this palette
-	 * Computes the "relative size" of a set of colors on this palette
-	 */
 	template<typename Iter>
 	auto combinedVolume(Iter &&begin, Iter &&end) const {
 		auto &colors = uniqueColors();

src/gfx/pal_sorting.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/pal_sorting.hpp"
 

src/gfx/pal_spec.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/pal_spec.hpp"
 
@@ -189,11 +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.
- *
- * @return true if a line was read.
- */
 [[gnu::warn_unused_result]] static bool readLine(std::filebuf &file, std::string &buffer) {
 	assume(buffer.empty());
 	// TODO: maybe this can be optimized to bulk reads?
@@ -222,9 +219,7 @@ static T readLE(U const *bytes) {
 		} \
 	} while (0)
 
-/*
+// Parses the initial part of a string_view, advancing the "read index" as it does
- * 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, std::string::size_type &n) {
 	uintmax_t value = 0;

src/gfx/process.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/process.hpp"
 
@@ -31,11 +31,9 @@ class ImagePalette {
 public:
 	ImagePalette() = default;
 
-	/*
+	// Registers a color in the palette.
-	 * Registers a color in the palette.
+	// If the newly inserted color "conflicts" with another one (different color, but same CGB
-	 * If the newly inserted color "conflicts" with another one (different color, but same CGB
+	// color), then the other color is returned. Otherwise, `nullptr` is returned.
-	 * color), then the other color is returned. Otherwise, `nullptr` is returned.
-	 */
 	[[nodiscard]] Rgba const *registerColor(Rgba const &rgba) {
 		decltype(_colors)::value_type &slot = _colors[rgba.cgbColor()];
 
@@ -165,15 +163,13 @@ public:
 		return true;
 	}
 
-	/*
+	// Reads a PNG and notes all of its colors
-	 * Reads a PNG and notes all of its colors
+	//
-	 *
+	// This code is more complicated than strictly necessary, but that's because of the API
-	 * This code is more complicated than strictly necessary, but that's because of the API
+	// being used: the "high-level" interface doesn't provide all the transformations we need,
-	 * being used: the "high-level" interface doesn't provide all the transformations we need,
+	// so we use the "lower-level" one instead.
-	 * so we use the "lower-level" one instead.
+	// We also use that occasion to only read the PNG one line at a time, since we store all of
-	 * We also use that occasion to only read the PNG one line at a time, since we store all of
+	// the pixel data in `pixels`, which saves on memory allocations.
-	 * the pixel data in `pixels`, which saves on memory allocations.
-	 */
 	explicit Png(std::string const &filePath) : path(filePath), colors() {
 		if (file.open(path, std::ios_base::in | std::ios_base::binary) == nullptr) {
 			fatal("Failed to open input image (\"%s\"): %s", file.c_str(path), strerror(errno));
@@ -490,9 +486,7 @@ public:
 };
 
 class RawTiles {
-	/*
+	// A tile which only contains indices into the image's global palette
-	 * A tile which only contains indices into the image's global palette
-	 */
 	class RawTile {
 		std::array<std::array<size_t, 8>, 8> _pixelIndices{};
 
@@ -505,9 +499,7 @@ private:
 	std::vector<RawTile> _tiles;
 
 public:
-	/*
+	// Creates a new raw tile, and returns a reference to it so it can be filled in
-	 * Creates a new raw tile, and returns a reference to it so it can be filled in
-	 */
 	RawTile &newTile() {
 		_tiles.emplace_back();
 		return _tiles.back();
@@ -515,11 +507,9 @@ public:
 };
 
 struct AttrmapEntry {
-	/*
+	// This field can either be a proto-palette ID, or `transparent` to indicate that the
-	 * This field can either be a proto-palette ID, or `transparent` to indicate that the
+	// corresponding tile is fully transparent. If you are looking to get the palette ID for this
-	 * corresponding tile is fully transparent. If you are looking to get the palette ID for this
+	// attrmap entry while correctly handling the above, use `getPalID`.
-	 * attrmap entry while correctly handling the above, use `getPalID`.
-	 */
 	size_t protoPaletteID; // Only this field is used when outputting "unoptimized" data
 	uint8_t tileID;        // This is the ID as it will be output to the tilemap
 	bool bank;
@@ -918,9 +908,7 @@ struct UniqueTiles {
 	UniqueTiles(UniqueTiles const &) = delete;
 	UniqueTiles(UniqueTiles &&) = default;
 
-	/*
+	// Adds a tile to the collection, and returns its ID
-	 * Adds a tile to the collection, and returns its ID
-	 */
 	std::tuple<uint16_t, TileData::MatchType> addTile(TileData newTile) {
 		auto [tileData, inserted] = tileset.insert(newTile);
 
@@ -942,12 +930,10 @@ struct UniqueTiles {
 	auto end() const { return tiles.end(); }
 };
 
-/*
+// Generate tile data while deduplicating unique tiles (via mirroring if enabled)
- * Generate tile data while deduplicating unique tiles (via mirroring if enabled)
+// Additionally, while we have the info handy, convert from the 16-bit "global" tile IDs to
- * Additionally, while we have the info handy, convert from the 16-bit "global" tile IDs to
+// 8-bit tile IDs + the bank bit; this will save the work when we output the data later (potentially
- * 8-bit tile IDs + the bank bit; this will save the work when we output the data later (potentially
+// twice)
- * twice)
- */
 static UniqueTiles dedupTiles(
     Png const &png,
     DefaultInitVec<AttrmapEntry> &attrmap,
@@ -1164,18 +1150,17 @@ void process() {
 				protoPalettes[n] = protoPalette; // Override them
 				// Remove any other proto-palettes that we encompass
 				// (Example [(0, 1), (0, 2)], inserting (0, 1, 2))
-				/*
+				//
-				 * The following code does its job, except that references to the removed
+				// The following code does its job, except that references to the removed
-				 * proto-palettes are not updated, causing issues.
+				// proto-palettes are not updated, causing issues.
-				 * TODO: overlap might not be detrimental to the packing algorithm.
+				// TODO: overlap might not be detrimental to the packing algorithm.
-				 * Investigation is necessary, especially if pathological cases are found.
+				// Investigation is necessary, especially if pathological cases are found.
-				 *
+				//
-				 * for (size_t i = protoPalettes.size(); --i != n;) {
+				// for (size_t i = protoPalettes.size(); --i != n;) {
-				 *     if (protoPalette.compare(protoPalettes[i]) == ProtoPalette::WE_BIGGER) {
+				//     if (protoPalette.compare(protoPalettes[i]) == ProtoPalette::WE_BIGGER) {
-				 *         protoPalettes.erase(protoPalettes.begin() + i);
+				//         protoPalettes.erase(protoPalettes.begin() + i);
-				 *     }
+				//     }
-				 * }
+				// }
-				 */
 				[[fallthrough]];
 
 			case ProtoPalette::THEY_BIGGER:

src/gfx/proto_palette.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/proto_palette.hpp"
 

src/gfx/reverse.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/reverse.hpp"
 

src/gfx/rgba.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "gfx/rgba.hpp"
 
@@ -10,11 +10,9 @@
 
 #include "gfx/main.hpp" // options
 
-/*
+// Based on inverting the "Modern - Accurate" formula used by SameBoy
- * Based on inverting the "Modern - Accurate" formula used by SameBoy
+// since commit b5a611c5db46d6a0649d04d24d8d6339200f9ca1 (Dec 2020),
- * since commit b5a611c5db46d6a0649d04d24d8d6339200f9ca1 (Dec 2020),
+// with gaps in the scale curve filled by polynomial interpolation.
- * with gaps in the scale curve filled by polynomial interpolation.
- */
 // clang-format off: vertically align columns of values
 static std::array<uint8_t, 256> reverse_curve{
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  1,  1,  1,  1,  1,

src/link/assign.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/assign.hpp"
 
@@ -48,11 +48,9 @@ static void initFreeSpace() {
 	}
 }
 
-/*
+// Assigns a section to a given memory location
- * Assigns a section to a given memory location
+// @param section The section to assign
- * @param section The section to assign
+// @param location The location to assign the section to
- * @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
@@ -66,15 +64,13 @@ static void assignSection(Section &section, MemoryLocation const &location) {
 	out_AddSection(section);
 }
 
-/*
+// Checks whether a given location is suitable for placing a given section
- * 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
- * This checks not only that the location has enough room for the section, but
+// also that the constraints (alignment...) are respected.
- * also that the constraints (alignment...) are respected.
+// @param section The section to be placed
- * @param section The section to be placed
+// @param freeSpace The candidate free space to place the section into
- * @param freeSpace The candidate free space to place the section into
+// @param location The location to attempt placing the section at
- * @param location The location to attempt placing the section at
+// @return True if the location is suitable, false otherwise.
- * @return True if the location is suitable, false otherwise.
- */
 static bool isLocationSuitable(
     Section const &section, FreeSpace const &freeSpace, MemoryLocation const &location
 ) {
@@ -90,13 +86,11 @@ static bool isLocationSuitable(
 	return location.address + section.size <= freeSpace.address + freeSpace.size;
 }
 
-/*
+// Finds a suitable location to place a section at.
- * Finds a suitable location to place a section at.
+// @param section The section to be placed
- * @param section The section to be placed
+// @param location A pointer to a memory location that will be filled
- * @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,
- * @return The index into `memory[section->type]` of the free space encompassing the location,
+//         or -1 if none was found
- *         or -1 if none was found
- */
 static ssize_t getPlacement(Section const &section, MemoryLocation &location) {
 	SectionTypeInfo const &typeInfo = sectionTypeInfo[section.type];
 
@@ -206,12 +200,10 @@ static ssize_t getPlacement(Section const &section, MemoryLocation &location) {
 	}
 }
 
-/*
+// Places a section in a suitable location, or error out if it fails to.
- * 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
- * @warning Due to the implemented algorithm, this should be called with
+//          sections of decreasing size.
- *          sections of decreasing size.
+// @param section The section to place
- * @param section The section to place
- */
 static void placeSection(Section &section) {
 	MemoryLocation location;
 
@@ -336,11 +328,9 @@ 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
- * @param section The section to categorize
- */
 static void categorizeSection(Section &section) {
 	uint8_t constraints = 0;
 

src/link/main.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include <sys/stat.h>
 #include <sys/types.h>
@@ -132,16 +132,13 @@ void argErr(char flag, char const *fmt, ...) {
 // Short options
 static char const *optstring = "dhl:m:Mn:O:o:p:S:tVvWwx";
 
-/*
+// Equivalent long options
- * Equivalent long options
+// Please keep in the same order as short opts.
- * Please keep in the same order as short opts
+// Also, make sure long opts don't create ambiguity:
- *
+// A long opt's name should start with the same letter as its short opt,
- * Also, make sure long opts don't create ambiguity:
+// except if it doesn't create any ambiguity (`verbose` versus `version`).
- * A long opt's name should start with the same letter as its short opt,
+// This is because long opt matching, even to a single char, is prioritized
- * except if it doesn't create any ambiguity (`verbose` versus `version`).
+// over short opt matching.
- * This is because long opt matching, even to a single char, is prioritized
- * over short opt matching
- */
 static option const longopts[] = {
     {"dmg",           no_argument,       nullptr, 'd'},
     {"help",          no_argument,       nullptr, 'h'},

src/link/object.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/object.hpp"
 
@@ -41,11 +41,9 @@ 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.
+// @param file The file to read from. This will read 4 bytes from the 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.
- * @return The value read, cast to a int64_t, or `INT64_MAX` on failure.
- */
 static int64_t readLong(FILE *file) {
 	uint32_t value = 0;
 
@@ -66,37 +64,31 @@ 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 for reading longs from a file, and errors out if it fails to.
+// Not as a function to avoid overhead in the general case.
- * Not as a function to avoid overhead in the general case.
+// @param var The variable to stash the number into
- * @param var The variable to stash the number into
+// @param file The file to read from. Its position will be advanced
- * @param file The file to read from. Its position will be advanced
+// @param ... A format string and related arguments; note that an extra string
- * @param ... A format string and related arguments; note that an extra string
+//            argument is provided, the reason for failure
- *            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`.
+// There is no `readByte`, just use `fgetc` or `getc`.
 
-/*
+// Helper macro for reading bytes from a file, and errors 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.
- * Not as a function to avoid overhead in the general case.
+// @param var The variable to stash the number into
- * @param var The variable to stash the number into
+// @param file The file to read from. Its position will be advanced
- * @param file The file to read from. Its position will be advanced
+// @param ... A format string and related arguments; note that an extra string
- * @param ... A format string and related arguments; note that an extra string
+//            argument is provided, the reason for failure
- *            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 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.
- * Not as a function to avoid overhead in the general case.
+// @param var The variable to stash the string into
- * @param var The variable to stash the string into
+// @param file The file to read from. Its position will be advanced
- * @param file The file to read from. Its position will be advanced
+// @param ... A format string and related arguments; note that an extra string
- * @param ... A format string and related arguments; note that an extra string
+//            argument is provided, the reason for failure
- *            argument is provided, the reason for failure
- */
 #define tryReadString(var, file, ...) \
 	do { \
 		FILE *tmpFile = file; \
@@ -112,13 +104,11 @@ static int64_t readLong(FILE *file) {
 
 // Functions to parse object files
 
-/*
+// Reads a file stack node form a file.
- * Reads a file stack node form a file.
+// @param file The file to read from
- * @param file The file to read from
+// @param nodes The file's array of nodes
- * @param nodes The file's array of nodes
+// @param i The ID of the node in the array
- * @param i The ID of the node in the array
+// @param fileName The filename to report in errors
- * @param fileName The filename to report in errors
- */
 static void readFileStackNode(
     FILE *file, std::vector<FileStackNode> &fileNodes, uint32_t i, char const *fileName
 ) {
@@ -171,12 +161,10 @@ static void readFileStackNode(
 	}
 }
 
-/*
+// Reads a symbol from a file.
- * Reads a symbol from a file.
+// @param file The file to read from
- * @param file The file to read from
+// @param symbol The symbol to fill
- * @param symbol The symbol to fill
+// @param fileName The filename to report in errors
- * @param fileName The filename to report in errors
- */
 static void readSymbol(
     FILE *file, Symbol &symbol, char const *fileName, std::vector<FileStackNode> const &fileNodes
 ) {
@@ -229,13 +217,11 @@ static void readSymbol(
 	}
 }
 
-/*
+// Reads a patch from a file.
- * Reads a patch from a file.
+// @param file The file to read from
- * @param file The file to read from
+// @param patch The patch to fill
- * @param patch The patch to fill
+// @param fileName The filename to report in errors
- * @param fileName The filename to report in errors
+// @param i The number of the patch to report in errors
- * @param i The number of the patch to report in errors
- */
 static void readPatch(
     FILE *file,
     Patch &patch,
@@ -320,22 +306,18 @@ static void readPatch(
 		);
 }
 
-/*
+// Sets a patch's pcSection from its pcSectionID.
- * Sets a patch's pcSection from its pcSectionID.
+// @param patch The patch to fix
- * @param patch The patch to fix
- */
 static void
     linkPatchToPCSect(Patch &patch, std::vector<std::unique_ptr<Section>> const &fileSections) {
 	patch.pcSection =
 	    patch.pcSectionID != UINT32_MAX ? fileSections[patch.pcSectionID].get() : nullptr;
 }
 
-/*
+// Reads a section from a file.
- * Reads a section from a file.
+// @param file The file to read from
- * @param file The file to read from
+// @param section The section to fill
- * @param section The section to fill
+// @param fileName The filename to report in errors
- * @param fileName The filename to report in errors
- */
 static void readSection(
     FILE *file, Section &section, char const *fileName, std::vector<FileStackNode> const &fileNodes
 ) {
@@ -440,11 +422,9 @@ static void readSection(
 	}
 }
 
-/*
+// Links a symbol to a section, keeping the section's symbol list sorted.
- * Links a symbol to a section, keeping the section's symbol list sorted.
+// @param symbol The symbol to link
- * @param symbol The symbol to link
+// @param section The section 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;
@@ -462,12 +442,10 @@ 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 file The file to read from
+// @param assert The assertion to fill
- * @param assert The assertion to fill
+// @param fileName The filename to report in errors
- * @param fileName The filename to report in errors
- */
 static void readAssertion(
     FILE *file,
     Assertion &assert,

src/link/output.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/output.hpp"
 
@@ -98,10 +98,8 @@ Section const *out_OverlappingSection(Section const &section) {
 	return nullptr;
 }
 
-/*
+// Performs sanity checks on the overlay file.
- * Performs sanity checks on the overlay file.
+// @return The number of ROM banks in the overlay file
- * @return The number of ROM banks in the overlay file
- */
 static uint32_t checkOverlaySize() {
 	if (!overlayFile)
 		return 0;
@@ -126,12 +124,10 @@ static uint32_t checkOverlaySize() {
 	return (overlaySize + BANK_SIZE - 1) / BANK_SIZE;
 }
 
-/*
+// Expand `sections[SECTTYPE_ROMX]` to cover all the overlay banks.
- * Expand `sections[SECTTYPE_ROMX]` to cover all the overlay banks.
+// This ensures that `writeROM` will output each bank, even if some are not
- * This ensures that `writeROM` will output each bank, even if some are not
+// covered by any sections.
- * covered by any sections.
+// @param nbOverlayBanks The number of banks in the overlay file
- * @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;
@@ -162,12 +158,10 @@ static uint8_t getNextFillByte() {
 	return padValue;
 }
 
-/*
+// Write a ROM bank's sections to the output file.
- * Write a ROM bank's sections to the output file.
+// @param bankSections The bank's sections, ordered by increasing address
- * @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 baseOffset The address of the bank's first byte in GB address space
+// @param size The size of the bank
- * @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;
@@ -327,10 +321,8 @@ static bool compareSymbols(SortedSymbol const &sym1, SortedSymbol const &sym2) {
 	return false;
 }
 
-/*
+// Write a bank's contents to the sym file
- * Write a bank's contents to the sym file
+// @param bankSections The bank's sections
- * @param bankSections The bank's sections
- */
 static void writeSymBank(SortedSections const &bankSections, SectionType type, uint32_t bank) {
 #define forEachSortedSection(sect, ...) \
 	do { \
@@ -421,9 +413,7 @@ static void printSectionName(std::string const &name, FILE *file) {
 	}
 }
 
-/*
+// Write a bank's contents to the map file
- * Write a bank's contents to the map file
- */
 static void writeMapBank(SortedSections const &sectList, SectionType type, uint32_t bank) {
 	fprintf(
 	    mapFile,
@@ -495,9 +485,7 @@ static void writeMapBank(SortedSections const &sectList, SectionType type, uint3
 	}
 }
 
-/*
+// Write the total used and free space by section type to the map file
- * Write the total used and free space by section type to the map file
- */
 static void writeMapSummary() {
 	fputs("SUMMARY:\n", mapFile);
 

src/link/patch.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/patch.hpp"
 
@@ -63,14 +63,12 @@ static Symbol const *getSymbol(std::vector<Symbol> const &symbolList, uint32_t i
 	return &symbol;
 }
 
-/*
+// Compute a patch's value from its RPN string.
- * Compute a patch's value from its RPN string.
+// @param patch The patch to compute the value of
- * @param patch The patch to compute the value of
+// @param section The section the patch is contained in
- * @param section The section the patch is contained in
+// @return The patch's value
- * @return The patch's value
+// @return isError Set if an error occurred during evaluation, and further
- * @return isError Set if an error occurred during evaluation, and further
+//                 errors caused by the value should be suppressed.
- *                 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());
@@ -471,11 +469,9 @@ void patch_CheckAssertions() {
 	}
 }
 
-/*
+// Applies all of a section's patches
- * Applies all of a section's patches
+// @param section The section component to patch
- * @param section The section component to patch
+// @param dataSection The section 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) {
@@ -537,10 +533,8 @@ static void applyFilePatches(Section &section, Section &dataSection) {
 	}
 }
 
-/*
+// Applies all of a section's patches, iterating over "components" of unionized sections
- * Applies all of a section's patches, iterating over "components" of unionized sections
+// @param section The section to patch
- * @param section The section to patch
- */
 static void applyPatches(Section &section) {
 	if (!sect_HasData(section.type))
 		return;

src/link/script.y

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 %language "c++"
 %define api.value.type variant

src/link/sdas_obj.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/sdas_obj.hpp"
 

src/link/section.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/section.hpp"
 

src/link/symbol.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "link/symbol.hpp"
 

src/linkdefs.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "linkdefs.hpp"
 
@@ -10,7 +10,7 @@ SectionTypeInfo sectionTypeInfo[SECTTYPE_INVALID] = {
     {
      .name = "WRAM0"s,
      .startAddr = 0xC000,
-     .size = 0x2000 /* Patched to 0x1000 if !isWRAM0Mode */,
+     .size = 0x2000, // Patched to 0x1000 if !isWRAM0Mode
      .firstBank = 0,
      .lastBank = 0,
      },
@@ -19,7 +19,7 @@ SectionTypeInfo sectionTypeInfo[SECTTYPE_INVALID] = {
      .startAddr = 0x8000,
      .size = 0x2000,
      .firstBank = 0,
-     .lastBank = 1 /* Patched to 0 if isDmgMode */,
+     .lastBank = 1, // Patched to 0 if isDmgMode
      },
     {
      .name = "ROMX"s,
@@ -31,7 +31,7 @@ SectionTypeInfo sectionTypeInfo[SECTTYPE_INVALID] = {
     {
      .name = "ROM0"s,
      .startAddr = 0x0000,
-     .size = 0x8000 /* Patched to 0x4000 if !is32kMode */,
+     .size = 0x8000, // Patched to 0x4000 if !is32kMode
      .firstBank = 0,
      .lastBank = 0,
      },

src/opmath.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 // Mathematical operators that don't reuse C++'s behavior
 

src/util.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "util.hpp"
 

src/version.cpp

@@ -1,4 +1,4 @@
-/* SPDX-License-Identifier: MIT */
+// SPDX-License-Identifier: MIT
 
 #include "version.hpp"