From ae279d1211bbb39a3967a6e1f714b28edf7646f2 Mon Sep 17 00:00:00 2001
From: "Azamat H. Hackimov" <azamat.hackimov@gmail.com>
Date: Sun, 7 Jul 2024 17:04:10 +0300
Subject: [PATCH] Documenting ISoundDevice classes

---
 libmve/movie_sound.h     | 19 +++++++++++++++++++
 libmve/sound_interface.h |  9 ++++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/libmve/movie_sound.h b/libmve/movie_sound.h
index 35572c0b..7779ca23 100644
--- a/libmve/movie_sound.h
+++ b/libmve/movie_sound.h
@@ -25,16 +25,35 @@
 
 namespace D3 {
 
+/// Implementation class for sound device used on movie playback.
 class MovieSoundDevice : ISoundDevice {
 private:
   SDL_AudioDeviceID m_device_id = 0;
 
 public:
+  /**
+   * Initialize sound device
+   * @param sample_rate sample rate in Hz (22050, 44100...)
+   * @param sample_size sample size (8, 16)
+   * @param channels count of channels (1 for mono, 2 for stereo)
+   * @param buf_size buffer size for SDL audio device
+   * @param is_compressed mark stream as compressed (on streaming will be used decompression functions)
+   */
   MovieSoundDevice(int sample_rate, uint16_t sample_size, uint8_t channels, uint32_t buf_size, bool is_compressed);
   ~MovieSoundDevice();
 
+  /**
+   * Check if sound device is properly initialized
+   * @return true on success
+   */
   [[nodiscard]] bool IsInitialized() const { return m_device_id > 0; }
 
+  /**
+   * Callback for filling SDL audio buffer
+   * @param userdata pointer to instance of this class
+   * @param stream stream that will be filled on callback
+   * @param len length of stream
+   */
   void static SDLAudioCallback(void *userdata, unsigned char *stream, int len);
 
   void Play() override;
diff --git a/libmve/sound_interface.h b/libmve/sound_interface.h
index 5dcfdd2e..250ab0bb 100644
--- a/libmve/sound_interface.h
+++ b/libmve/sound_interface.h
@@ -25,19 +25,26 @@
 
 namespace D3 {
 
+/// Abstract class for sound device.
 class ISoundDevice {
 protected:
   std::unique_ptr<std::deque<int16_t>> m_sound_buffer;
   bool m_is_compressed = false;
 
 public:
-  ISoundDevice() { m_sound_buffer = std::make_unique<std::deque<int16_t>>(); };
+  ISoundDevice() { this->m_sound_buffer = std::make_unique<std::deque<int16_t>>(); };
+  /// Play stream
   virtual void Play() {};
+  /// Stop stream
   virtual void Stop() {};
+  /// Lock buffer for various atomic operations
   virtual void Lock() {};
+  /// Unlock buffer
   virtual void Unlock() {};
 
+  /// Get access to sound buffer
   std::unique_ptr<std::deque<int16_t>> &GetBuffer() { return m_sound_buffer; }
+  /// Check if encoded sound is compressed
   [[nodiscard]] bool IsCompressed() const { return m_is_compressed; };
 
 };