📝 Add docstrings to refactor

Docstrings generation was requested by @Raffaello.

* #285 (comment)

The following files were modified:

* `sdl2-hyper-sonic-drivers/examples/adl-play.cpp`
* `sdl2-hyper-sonic-drivers/sdl2-hyper-sonic-drivers.cpp`
* `sdl2-hyper-sonic-drivers/src/HyperSonicDrivers/files/westwood/ADLFile.cpp`
* `sdl2-hyper-sonic-drivers/test/HyperSonicDrivers/files/westwood/TestADLFile.cpp`

Author: coderabbitai[bot]

sdl2-hyper-sonic-drivers/examples/adl-play.cpp

@@ -29,6 +29,32 @@ using files::westwood::ADLFile;
 using drivers::westwood::ADLDriver;
 
 
+/**
+ * @brief Play an ADL file using a chosen OPL emulator/type until the user exits.
+ *
+ * Plays the given ADL file through an OPL device constructed from the specified
+ * emulator and OPL type. The function creates an ADLDriver bound to the
+ * Music channel group and enters an SDL event-driven loop that starts playback
+ * (initial track index is 5) and responds to key presses to control playback.
+ *
+ * Behavior:
+ * - Selects an OPL device based on `type`:
+ *   - OPL2     -> Adlib + Opl
+ *   - DUAL_OPL2-> SbPro  + Opl
+ *   - OPL3     -> SbPro2 + Opl
+ * - If the provided mixer is not ready, logs an error and returns immediately.
+ * - Starts playing the current track when not already playing.
+ * - Key controls (during playback):
+ *   - ESC: stop all channels and return (exit function)
+ *   - RIGHT: stop channels and advance to the next track (wraps to 0)
+ *   - LEFT: stop channels and go to the previous track (wraps to last)
+ *
+ * This function blocks until ESC is pressed.
+ *
+ * @param emu  OPL emulator selection used when constructing the device.
+ * @param type OPL hardware type used to choose the concrete device implementation.
+ * @param filename Path to the ADL file to load and play.
+ */
 void adl_play(const OplEmulator emu, const OplType type, std::shared_ptr<audio::IMixer> mixer, const std::string& filename)
 {
     using devices::make_device;
@@ -106,6 +132,20 @@ void adl_play(const OplEmulator emu, const OplType type, std::shared_ptr<audio::
     } while (true);
 }
 
+/**
+ * @brief Program entry point for the ADL playback demo using SDL2 and OPL emulation.
+ *
+ * Initializes SDL video, creates a minimal SDL window, and starts an SDL-based audio mixer.
+ * Iterates over configured OPL emulator and OPL type combinations, prints a colored header
+ * for each pair, and invokes adl_play to run the ADL playback demo for "DUNE0.ADL".
+ * Cleans up SDL resources before exiting.
+ *
+ * Return codes:
+ *  -  0 : Normal exit after running demos and cleanup.
+ *  -  1 : Mixer initialization failed.
+ *  - -1 : SDL video initialization failed.
+ *  - -2 : SDL window creation failed.
+ */
 int main(int argc, char* argv[])
 {
     if (SDL_Init(SDL_INIT_VIDEO) != 0)

sdl2-hyper-sonic-drivers/sdl2-hyper-sonic-drivers.cpp

@@ -1,4 +1,4 @@
-// sdl2-hyper-sonic-drivers.cpp : Defines the entry point for the application.
+// sdl2-hyper-sonic-drivers.cpp : Defines the entry point for the application.
 // TODO: delete this file and its target, this is kinda scratch pad
 
 #include <iostream>
@@ -336,6 +336,16 @@ void testMT32()
 }
 
 
+/**
+ * @brief Load a WAV fixture, append it to itself, and play the result to completion.
+ *
+ * Initializes an SDL2 mixer, loads "test/fixtures/test_renderer_adlib_mame2.wav" into two sound
+ * objects, concatenates them into a single PCM sound, and plays that combined sound via a
+ * PCMDriver. The function blocks, polling until playback finishes.
+ *
+ * @note This function is a test utility: it uses a hard-coded test fixture path and performs
+ * synchronous waiting while playback is active.
+ */
 void pcm_sound_append()
 {
     auto mixer = audio::make_mixer<audio::sdl2::Mixer>(8, 44100, 1024);
@@ -356,6 +366,24 @@ void pcm_sound_append()
     }
 }
 
+/**
+ * @brief Test harness that plays Westwood ADL music tracks through an Adlib/OPL driver using SDL2.
+ *
+ * This routine initializes an SDL2-backed audio mixer and an Adlib/OPL device, loads a Westwood
+ * ADL file (fixed to "adl/KYRA1A.ADL"), and uses drivers::westwood::ADLDriver to play each
+ * track (tracks are iterated from index 1 to getNumTracks()-1). Each track is played up to three
+ * times. The function creates a small SDL window and pumps SDL events while waiting for playback
+ * to finish; pressing Escape or receiving SDL_QUIT will abort the test, and pressing Return stops
+ * the current track. After completing playback or aborting, the SDL window is destroyed.
+ *
+ * Side effects:
+ * - Initializes SDL event and video subsystems and creates an SDL window.
+ * - Initializes audio mixer and constructs Adlib/OPL device and ADL driver.
+ * - Blocks while tracks are playing (polls events and sleeps).
+ *
+ * Notes:
+ * - File name and iteration counts are hard-coded for this test harness.
+ */
 void adldune2filestest()
 {
     auto mixer = audio::make_mixer<audio::sdl2::Mixer>(8, 44100, 1024);
@@ -414,6 +442,18 @@ void adldune2filestest()
     SDL_DestroyWindow(window);
 }
 
+/**
+ * @brief Plays VOC files through an Adlib/OPL-backed PCM driver using SDL for event handling.
+ *
+ * Initializes an SDL-backed audio mixer and Adlib/OPL device, scans the local "voc/" directory,
+ * and plays each VOC file's PCM sound multiple times. While a sound is playing the function
+ * processes SDL events so the user can quit (window close or Escape) or stop the current playback
+ * early (Enter). A small SDL window is created for event delivery and destroyed on exit.
+ *
+ * This is a test/harness routine with side effects: it initializes SDL subsystems, creates an
+ * audio mixer and device, opens a window, iterates the filesystem, and drives playback via a
+ * PCMDriver. It does not return any value.
+ */
 void vocdune2filestest()
 {
     auto mixer = audio::make_mixer<audio::sdl2::Mixer>(8, 44100, 1024);
@@ -466,6 +506,19 @@ void vocdune2filestest()
     SDL_DestroyWindow(window);
 }
 
+/**
+ * @brief Program entry point that runs selected test routines.
+ *
+ * The main function serves as the test harness entry. It dispatches to various
+ * SDL2/HyperSonicDrivers test routines; currently it invokes adldune2filestest()
+ * and then returns immediately. The function performs global initialization
+ * and teardown only for the test routines it calls (handled by those routines).
+ *
+ * Note: many test calls are present but commented out; uncommenting changes the
+ * executed test sequence.
+ *
+ * @return int Process exit code (0 on normal completion).
+ */
 int main(int argc, char* argv[])
 {
     //newMixerTest();

sdl2-hyper-sonic-drivers/src/HyperSonicDrivers/files/westwood/ADLFile.cpp

@@ -91,6 +91,27 @@ namespace HyperSonicDrivers::files::westwood
         V3_DATA_HEADER_SIZE
     };
 
+    /**
+     * @brief Construct an ADLFile by loading and parsing a Westwood ADL file from disk.
+     *
+     * Reads the file header, track offsets, instrument offsets and raw data payload
+     * according to the detected ADL version (V1/V2/V3), validates sizes, computes
+     * counts for tracks/offsets, then closes the file and converts absolute offsets
+     * into data-relative offsets (using 0xFFFF as the sentinel for invalid entries).
+     *
+     * The constructor:
+     * - validates the file meets the minimum size for an ADL file,
+     * - determines the on-disk ADL version and associated metadata,
+     * - reads version-appropriate header entries,
+     * - reads track and instrument offset tables,
+     * - reads the raw data payload and stores its size/header size,
+     * - sets m_num_tracks from the version metadata and computes the number of
+     *   valid track/instrument offsets,
+     * - closes the underlying file handle,
+     * - adjusts offsets to be relative to the in-memory data payload (and maps 0 -> 0xFFFF).
+     *
+     * @param filename Path to the ADL file to open and parse.
+     */
     ADLFile::ADLFile(const std::string& filename) : File(filename)
     {
         assertValid_(size() >= FILE_SIZE_MIN);
@@ -137,6 +158,16 @@ namespace HyperSonicDrivers::files::westwood
         return m_version;
     }
 
+    /**
+     * @brief Return the number of tracks (subsongs) in the ADL file.
+     *
+     * The value is the internally stored track count determined at file load
+     * from the version-specific metadata. For some V3 files the in-memory
+     * header is known to be incorrect, so this returned count reflects the
+     * metadata-derived value rather than any inferred count from the header.
+     *
+     * @return int Number of tracks (subsongs).
+     */
     int ADLFile::getNumTracks() const noexcept
     {
         return m_num_tracks;
@@ -155,6 +186,16 @@ namespace HyperSonicDrivers::files::westwood
         //return numSubSongs;
     }
 
+    /**
+     * @brief Return the number of program (track) offsets present in the ADL file.
+     *
+     * This value is determined during construction from the file's version-specific
+     * metadata and offset tables. It represents how many valid track/program
+     * offset entries are available (sentinel/invalid entries are counted according
+     * to the parsed offset table).
+     *
+     * @return int Number of track/program offsets.
+     */
     int ADLFile::getNumTrackOffsets() const noexcept
     {
         return m_num_track_offsets;
@@ -281,6 +322,19 @@ namespace HyperSonicDrivers::files::westwood
         }
     }
 
+    /**
+     * @brief Read and populate the in-memory header table from the open file.
+     *
+     * Resizes ADLFile::m_header to header_size and fills it by invoking the supplied
+     * read callback header_size times. The read callback is expected to return the
+     * next header entry (as a 16-bit value) each time it is called. After reading,
+     * the method validates that the header vector length matches header_size.
+     *
+     * @param header_size Number of header entries to read and store into m_header.
+     * @param read A zero-argument callable that returns the next header entry as uint16_t.
+     *             The caller is responsible for using the correct byte-width and endianness
+     *             for the target ADL version.
+     */
     void ADLFile::readHeaderFromFile_(const int header_size, std::function<uint16_t()> read)
     {
         m_header.resize(header_size);

sdl2-hyper-sonic-drivers/test/HyperSonicDrivers/files/westwood/TestADLFile.cpp

@@ -74,6 +74,14 @@ namespace HyperSonicDrivers::files::westwood
         EXPECT_EQ(chan, 9);
     }
 
+    /**
+     * @brief Tests ADLFile parsing for a version 3 ADL fixture (LOREINTR.ADL).
+     *
+     * Verifies that the file is recognized as version 3, reports the expected
+     * counts (tracks, track offsets, instrument offsets) and data size, and that
+     * program offsets for a track resolve to the corresponding track and
+     * instrument offsets. Also checks that the first track's data byte equals 9.
+     */
     TEST(ADLFile, ADLv3)
     {
         ADLFile f("../fixtures/LOREINTR.ADL");