add fn comments for doxygen, rename OAMTile to OamTile

src/app/editor/context/entrance_context.h

@@ -10,6 +10,7 @@
 namespace yaze {
 namespace app {
 namespace editor {
+namespace context {
 
 class EntranceContext {
  public:
@@ -33,6 +34,7 @@ class EntranceContext {
   std::vector<uint16_t> entrance_tile_types_high_;
 };
 
+}  // namespace context
 }  // namespace editor
 }  // namespace app
 }  // namespace yaze

src/app/editor/context/gfx_context.cc

@@ -5,22 +5,23 @@
 #include <cmath>
 
 #include "app/core/editor.h"
-#include "app/gui/pipeline.h"
 #include "app/editor/modules/palette_editor.h"
 #include "app/gfx/bitmap.h"
 #include "app/gfx/snes_palette.h"
 #include "app/gfx/snes_tile.h"
 #include "app/gui/canvas.h"
 #include "app/gui/icons.h"
+#include "app/gui/pipeline.h"
 #include "app/rom.h"
 
 namespace yaze {
 namespace app {
 namespace editor {
-
+namespace context {
 
 std::unordered_map<uint8_t, gfx::Paletteset> GfxContext::palettesets_;
 
+}
 }  // namespace editor
 }  // namespace app
 }  // namespace yaze

src/app/editor/context/gfx_context.h

@@ -19,7 +19,11 @@
 namespace yaze {
 namespace app {
 namespace editor {
+namespace context {
 
+/**
+ * @brief Shared graphical context across editors.
+ */
 class GfxContext {
  public:
   absl::Status Update();
@@ -29,6 +33,7 @@ class GfxContext {
   static std::unordered_map<uint8_t, gfx::Paletteset> palettesets_;
 };
 
+}  // namespace context
 }  // namespace editor
 }  // namespace app
 }  // namespace yaze

src/app/editor/graphics_editor.h

@@ -59,6 +59,9 @@ constexpr ImGuiTableFlags kGfxEditFlags = ImGuiTableFlags_Reorderable |
                                           ImGuiTableFlags_Resizable |
                                           ImGuiTableFlags_SizingStretchSame;
 
+/**
+ * @brief Manages the games graphical content.
+*/
 class GraphicsEditor : public SharedROM {
  public:
   absl::Status Update();

src/app/editor/master_editor.h

@@ -35,7 +35,7 @@ namespace app {
 namespace editor {
 
 class MasterEditor : public SharedROM,
-                     public GfxContext,
+                     public context::GfxContext,
                      public core::ExperimentFlags {
  public:
   MasterEditor() { current_editor_ = &overworld_editor_; }

src/app/editor/modules/palette_editor.h

@@ -25,6 +25,7 @@ static constexpr absl::string_view kPaletteGroupNames[] = {
     "ow_aux",      "global_sprites", "dungeon_main", "ow_mini_map",
     "ow_mini_map", "3d_object",      "3d_object"};
 
+namespace palette_internal {
 struct PaletteChange {
   std::string group_name;
   size_t palette_index;
@@ -74,6 +75,7 @@ class PaletteEditorHistory {
   std::deque<PaletteChange> recentChanges;
   static const size_t maxHistorySize = 50;  // or any other number you deem fit
 };
+}  // namespace palette_internal
 
 class PaletteEditor : public SharedROM {
  public:
@@ -103,7 +105,7 @@ class PaletteEditor : public SharedROM {
 
   absl::Status status_;
 
-  PaletteEditorHistory history_;
+  palette_internal::PaletteEditorHistory history_;
 
   ImVec4 saved_palette_[256] = {};
   gfx::SnesColor current_color_;

src/app/editor/modules/tile16_editor.h

@@ -24,7 +24,10 @@ namespace yaze {
 namespace app {
 namespace editor {
 
-class Tile16Editor : public GfxContext, public SharedROM {
+/**
+ * @brief Popup window to edit Tile16 data
+ */
+class Tile16Editor : public context::GfxContext, public SharedROM {
  public:
   absl::Status Update();
   absl::Status DrawMenu();

src/app/editor/overworld_editor.h

@@ -64,8 +64,8 @@ constexpr absl::string_view kOWMapTable = "#MapSettingsTable";
 
 class OverworldEditor : public Editor,
                         public SharedROM,
-                        public GfxContext,
-                        public EntranceContext,
+                        public context::GfxContext,
+                        public context::EntranceContext,
                         public core::ExperimentFlags {
  public:
   absl::Status Update() final;

src/app/gfx/bitmap.h

@@ -17,9 +17,17 @@ namespace yaze {
 namespace app {
 namespace gfx {
 
+/**
+ * @brief Convert SDL_Surface to PNG image data.
+ */
 bool ConvertSurfaceToPNG(SDL_Surface *surface, std::vector<uint8_t> &buffer);
+
+/**
+ * @brief Convert PNG image data to SDL_Surface.
+ */
 void ConvertPngToSurface(const std::vector<uint8_t> &png_data,
                          SDL_Surface **outSurface);
+
 class Bitmap {
  public:
   Bitmap() = default;
@@ -30,13 +38,30 @@ class Bitmap {
     InitializeFromData(width, height, depth, data);
   }
 
+  /**
+   * @brief Creates a bitmap object and reserves space for graphical data.
+   */
   void Create(int width, int height, int depth, int data_size);
+
+  /**
+   * @brief Creates a bitmap object with the provided graphical data.
+   */
   void Create(int width, int height, int depth, const Bytes &data);
 
   void InitializeFromData(uint32_t width, uint32_t height, uint32_t depth,
                           const Bytes &data);
 
+  /**
+   * @brief Creates the underlying SDL_Texture to be displayed.
+   *
+   * Converts the surface from a RGB to ARGB format.
+   * Uses SDL_TEXTUREACCESS_STREAMING to allow for live updates.
+   */
   void CreateTexture(std::shared_ptr<SDL_Renderer> renderer);
+
+  /**
+   * @brief Updates the underlying SDL_Texture when it already exists.
+   */
   void UpdateTexture(std::shared_ptr<SDL_Renderer> renderer);
   void CreateTexture(SDL_Renderer *renderer);
   void UpdateTexture(SDL_Renderer *renderer, bool use_sdl_update = false);
@@ -47,6 +72,9 @@ class Bitmap {
   void LoadFromPngData(const std::vector<uint8_t> &png_data, int width,
                        int height);
 
+  /**
+   * @brief Copy color data from the SnesPalette into the SDL_Palette
+   */
   absl::Status ApplyPalette(const SnesPalette &palette);
   absl::Status ApplyPaletteWithTransparent(const SnesPalette &palette,
                                            int index, int length = 7);
@@ -237,6 +265,9 @@ class Bitmap {
 
 using BitmapTable = std::unordered_map<int, gfx::Bitmap>;
 
+/**
+ * @brief Hash map container of shared pointers to Bitmaps.
+ */
 class BitmapManager {
  private:
   std::unordered_map<int, std::shared_ptr<gfx::Bitmap>> bitmap_cache_;

src/app/gfx/snes_color.h

@@ -10,6 +10,9 @@ namespace yaze {
 namespace app {
 namespace gfx {
 
+/**
+ * @brief Primitive of 16-bit RGB SNES color.
+ */
 struct snes_color {
   uint16_t red;   /**< Red component of the color. */
   uint16_t blue;  /**< Blue component of the color. */
@@ -26,6 +29,16 @@ std::vector<snes_color> Extract(const char* data, unsigned int offset,
 
 std::vector<char> Convert(const std::vector<snes_color>& palette);
 
+/**
+ * @brief SNES Color container
+ * 
+ * Used for displaying the color to the screen and writing 
+ * the color to the ROM file in the correct format.
+ * 
+ * SNES colors may be represented in one of three formats:
+ *  - Color data from the rom in a snes_color struct
+ *  - Color data for displaying to the UI via ImVec4
+ */
 class SnesColor {
  public:
   SnesColor() : rgb_(0.f, 0.f, 0.f, 0.f), snes_(0) {}
@@ -53,6 +66,7 @@ class SnesColor {
   }
 
   ImVec4 rgb() const { return rgb_; }
+
   void set_rgb(const ImVec4 val) {
     rgb_.x = val.x / 255;
     rgb_.y = val.y / 255;
@@ -65,6 +79,7 @@ class SnesColor {
     snes_ = ConvertRGBtoSNES(color);
     modified = true;
   }
+
   void set_snes(uint16_t val) {
     snes_ = val;
     snes_color col = ConvertSNEStoRGB(val);

src/app/gfx/snes_palette.h

@@ -21,6 +21,9 @@ namespace yaze {
 namespace app {
 namespace gfx {
 
+/**
+ * @brief Primitive of a SNES color palette.
+ */
 struct snes_palette {
   uint id;            /**< ID of the palette. */
   uint size;          /**< Size of the palette. */
@@ -31,6 +34,9 @@ using snes_palette = struct snes_palette;
 uint32_t GetPaletteAddress(const std::string& group_name, size_t palette_index,
                            size_t color_index);
 
+/**
+ * @brief SNES Palette container
+*/
 class SnesPalette {
  public:
   template <typename T>

src/app/gfx/snes_tile.h

@@ -35,9 +35,14 @@ std::vector<uint8_t> ConvertBpp(const std::vector<uint8_t>& tiles,
 std::vector<uint8_t> Convert3bppTo4bpp(const std::vector<uint8_t>& tiles);
 std::vector<uint8_t> Convert4bppTo3bpp(const std::vector<uint8_t>& tiles);
 
-// vhopppcc cccccccc
-// [0, 1]
-// [2, 3]
+/**
+ * @brief SNES 16-bit tile metadata container
+ *
+ * Format:
+ *  vhopppcc cccccccc
+ *     [0, 1]
+ *     [2, 3]
+ */
 class TileInfo {
  public:
   uint16_t id_;
@@ -67,6 +72,9 @@ uint16_t TileInfoToShort(TileInfo tile_info);
 
 TileInfo GetTilesInfo(uint16_t tile);
 
+/**
+ * @brief Tile composition of four 16x16 tiles.
+ */
 class Tile32 {
  public:
   uint16_t tile0_;
@@ -113,6 +121,9 @@ class Tile32 {
   bool operator!=(const Tile32& other) const { return !(*this == other); }
 };
 
+/**
+ * @brief Tile composition of four 8x8 tiles.
+ */
 class Tile16 {
  public:
   TileInfo tile0_;
@@ -138,7 +149,10 @@ class Tile16 {
   bool operator!=(const Tile16& other) const { return !(*this == other); }
 };
 
-class OAMTile {
+/**
+ * @brief Object Attribute Memory tile abstraction container
+*/
+class OamTile {
  public:
   int x_;
   int y_;
@@ -146,8 +160,8 @@ class OAMTile {
   int my_;
   int pal_;
   uint16_t tile_;
-  OAMTile() = default;
-  OAMTile(int x, int y, uint16_t tile, int pal, bool upper = false, int mx = 0,
+  OamTile() = default;
+  OamTile(int x, int y, uint16_t tile, int pal, bool upper = false, int mx = 0,
           int my = 0)
       : x_(x), y_(y), mx_(mx), my_(my), pal_(pal) {
     if (upper) {

src/app/zelda3/common.h

@@ -4,8 +4,8 @@
 namespace yaze {
 namespace app {
 /**
- * @brief Zelda 3 specific classes and functions.
  * @namespace zelda3
+ * @brief Zelda 3 specific classes and functions.
  */
 namespace zelda3 {
 

src/app/zelda3/overworld_map.h

@@ -23,9 +23,10 @@ namespace zelda3 {
 
 static constexpr int kTileOffsets[] = {0, 8, 4096, 4104};
 
-using editor::GfxContext;
-
-class OverworldMap : public GfxContext {
+/**
+ * @brief Represents a single Overworld map screen.
+ */
+class OverworldMap : public editor::context::GfxContext {
  public:
   OverworldMap() = default;
   OverworldMap(int index, ROM& rom, std::vector<gfx::Tile16>& tiles16);

src/app/zelda3/screen/title_screen.h

@@ -64,9 +64,9 @@ class TitleScreen {
 
   ROM rom_;
 
-  gfx::OAMTile oam_data[10];
-  gfx::OAMTile selected_oam_tile;
-  gfx::OAMTile last_selected_oam_tile;
+  gfx::OamTile oam_data[10];
+  gfx::OamTile selected_oam_tile;
+  gfx::OamTile last_selected_oam_tile;
 
   gfx::Bitmap tilesBG1Bitmap;  // 0x80000
   gfx::Bitmap tilesBG2Bitmap;  // 0x80000