add zelda3::music namespace, update documentation

src/app/core/controller.h

@@ -11,8 +11,8 @@
 
 #include "absl/status/status.h"
 #include "app/core/common.h"
-#include "app/editor/utils/editor.h"
 #include "app/editor/master_editor.h"
+#include "app/editor/utils/editor.h"
 #include "app/gui/icons.h"
 #include "app/gui/style.h"
 
@@ -22,6 +22,12 @@ namespace yaze {
 namespace app {
 namespace core {
 
+/**
+ * @brief Main controller for the application.
+ *
+ * This class is responsible for managing the main window and the
+ * main editor. It is the main entry point for the application.
+ */
 class Controller : public ExperimentFlags {
  public:
   bool IsActive() const { return active_; }

src/app/editor/modules/music_editor.h

@@ -70,7 +70,7 @@ class MusicEditor : public SharedROM {
   void DrawSongToolset();
   void DrawToolset();
 
-  zelda3::Tracker music_tracker_;
+  zelda3::music::Tracker music_tracker_;
 
   // Mix_Music* current_song_ = NULL;
 

src/app/gfx/snes_palette.h

@@ -140,6 +140,12 @@ SnesPalette ReadPaletteFromRom(int offset, int num_colors, const uint8_t* rom);
 
 std::array<float, 4> ToFloatArray(const SnesColor& color);
 
+/**
+ * @brief Represents a group of palettes.
+ *
+ * Supports adding palettes and colors, clearing the group, and accessing
+ * palettes and colors by index.
+ */
 struct PaletteGroup {
   PaletteGroup() = default;
 

src/app/yaze.cc

@@ -8,6 +8,15 @@
 #include "absl/debugging/symbolize.h"
 #include "app/core/controller.h"
 
+/**
+ * @namespace yaze::app
+ * @brief Main namespace for the ImGui application.
+ */
+using namespace yaze::app;
+
+/**
+ * @brief Main entry point for the application.
+ */
 int main(int argc, char** argv) {
   absl::InitializeSymbolizer(argv[0]);
 
@@ -16,7 +25,7 @@ int main(int argc, char** argv) {
   options.alarm_on_failure_secs = true;
   absl::InstallFailureSignalHandler(options);
 
-  yaze::app::core::Controller controller;
+  core::Controller controller;
   EXIT_IF_ERROR(controller.OnEntry())
 
 #ifdef __APPLE__

src/app/zelda3/music/tracker.cc

@@ -28,7 +28,7 @@ namespace zelda3 {
 
 namespace {
 
-void AddSPCReloc(SongSPCBlock *sbl, short addr) {
+void AddSPCReloc(music::SongSPCBlock *sbl, short addr) {
   sbl->relocs[sbl->relnum++] = addr;
   if (sbl->relnum == sbl->relsz) {
     sbl->relsz += 16;
@@ -38,8 +38,7 @@ void AddSPCReloc(SongSPCBlock *sbl, short addr) {
 
 }  // namespace
 
-// =============================================================================
-
+namespace music {
 SongSPCBlock *Tracker::AllocSPCBlock(int len, int bank) {
   SongSPCBlock *sbl;
   if (!len) {
@@ -1337,8 +1336,7 @@ void Tracker::NewSR(ROM &rom, int bank) {
   EditTrack(rom, sr->first);
 }
 
-// =============================================================================
-
+}  // namespace music
 }  // namespace zelda3
 }  // namespace app
 }  // namespace yaze

src/app/zelda3/music/tracker.h

@@ -17,6 +17,14 @@
 namespace yaze {
 namespace app {
 namespace zelda3 {
+  
+/**
+ * @namespace yaze::app::zelda3::music
+ * @brief Contains classes and functions for handling music data in Zelda 3.
+ *
+ * Based off of the HyruleMagic tracker code.
+ */
+namespace music {
 
 // bank 19, 1A, 1B
 // iirc 1A is OW, 1B is dungeon
@@ -84,7 +92,7 @@ using Song = struct {
   short numparts;
   short lopst;
   unsigned short addr;
-  bool in_use; // true
+  bool in_use;  // true
 };
 // =============================================================================
 
@@ -252,6 +260,7 @@ class Tracker {
 
 // =============================================================================
 
+}  // namespace music
 }  // namespace zelda3
 }  // namespace app
 }  // namespace yaze

src/app/zelda3/overworld.h

@@ -468,6 +468,12 @@ struct MapData {
   std::vector<uint8_t> lowData;
 };
 
+/**
+ * @brief Represents the full Overworld data, light and dark world.
+ *
+ * This class is responsible for loading and saving the overworld data,
+ * as well as creating the tilesets and tilemaps for the overworld.
+ */
 class Overworld : public SharedROM, public core::ExperimentFlags {
  public:
   OWBlockset &GetMapTiles(int world_type);

src/cli/command_handler.h

@@ -104,6 +104,9 @@ class CreatePatch : public CommandHandler {
   }
 };
 
+/**
+ * @brief Open a ROM file and display information about it.
+ */
 class Open : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -119,7 +122,9 @@ class Open : public CommandHandler {
   }
 };
 
-// Backup ROM
+/**
+ * @brief Backup a ROM file.
+ */
 class Backup : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -185,8 +190,12 @@ class Decompress : public CommandHandler {
   }
 };
 
-// SnesToPc Conversion
-// -s <address>
+/**
+ * @brief Convert a SNES address to a PC address.
+
+  * @param arg_vec `-s <address>`
+  * @return absl::Status
+*/
 class SnesToPc : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -200,6 +209,12 @@ class SnesToPc : public CommandHandler {
   }
 };
 
+/**
+ * @brief Convert a PC address to a SNES address.
+
+  * @param arg_vec `-p <address>`
+  * @return absl::Status
+*/
 class PcToSnes : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -216,7 +231,12 @@ class PcToSnes : public CommandHandler {
   }
 };
 
-// -r <rom_file> <address> <optional:length, default: 0x01>
+/**
+ * @brief Read from a ROM file.
+
+  * @param arg_vec `-r <rom_file> <address> <optional:length, default: 0x01>`
+  * @return absl::Status
+*/
 class ReadFromRom : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -249,13 +269,23 @@ class ReadFromRom : public CommandHandler {
   }
 };
 
-// Transfer tile 16 data from one rom to another
-// -t <src_rom> <dest_rom> "<tile32_id_list:csv>"
+/**
+ * @brief Transfer tile 16 data from one ROM to another.
+
+  * @param arg_vec `-t <src_rom> <dest_rom> "<tile32_id_list:csv>"`
+  * @return absl::Status
+*/
 class Tile16Transfer : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override;
 };
 
+/**
+ * @brief Expand a ROM file.
+
+  * @param arg_vec `-x <rom_file> <file_size>`
+  * @return absl::Status
+*/
 class Expand : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -274,8 +304,12 @@ class Expand : public CommandHandler {
   }
 };
 
-// Start Emulator on a SNES rom file
-// -emu <rom_file> <optional:num_cpu_cycles>
+/**
+ * @brief Start the emulator on a SNES ROM file.
+
+  * @param arg_vec `-emu <rom_file> <optional:num_cpu_cycles>`
+  * @return absl::Status
+*/
 class Emulator : public CommandHandler {
  public:
   absl::Status handle(const std::vector<std::string>& arg_vec) override {
@@ -321,6 +355,9 @@ class Emulator : public CommandHandler {
   app::emu::SNES snes;
 };
 
+/**
+ * @brief Command handler for the CLI.
+ */
 struct Commands {
   std::unordered_map<std::string, std::shared_ptr<CommandHandler>> handlers = {
       {"-emu", std::make_shared<Emulator>()},

src/cli/z3ed.cc

@@ -16,6 +16,11 @@
 #include "cli/patch.h"
 
 namespace yaze {
+
+/**
+ * @namespace yaze::cli
+ * @brief Namespace for the command line interface.
+ */
 namespace cli {
 namespace {