From 835e4845f8817646ca532d875db5692c74e5646b Mon Sep 17 00:00:00 2001
From: Simon Weis <laguna.ws@gmail.com>
Date: Mon, 18 Dec 2023 08:46:19 +0100
Subject: [PATCH] Add documentation

---
 .../sound_context/sound_context_interface.hpp |  2 ++
 impl/oalpp/sound_data/sound_data_builder.cpp  |  4 ++++
 impl/oalpp/sound_data/sound_data_builder.hpp  | 22 ++++++++++++++++++-
 .../oalpp/sound_data/sound_data_interface.hpp | 16 +++++++++++---
 4 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/impl/oalpp/sound_context/sound_context_interface.hpp b/impl/oalpp/sound_context/sound_context_interface.hpp
index 83957a6..385e208 100644
--- a/impl/oalpp/sound_context/sound_context_interface.hpp
+++ b/impl/oalpp/sound_context/sound_context_interface.hpp
@@ -2,6 +2,7 @@
 #define OPENALPP_SOUNDCONTEXTINTERFACE_HPP
 
 namespace oalpp {
+
 class SoundContextInterface {
 public:
     virtual ~SoundContextInterface() = default;
@@ -16,6 +17,7 @@ class SoundContextInterface {
     // allow default construction for derived classes
     SoundContextInterface() = default;
 };
+
 } // namespace oalpp
 
 #endif // OPENALPP_SOUNDCONTEXTINTERFACE_HPP
diff --git a/impl/oalpp/sound_data/sound_data_builder.cpp b/impl/oalpp/sound_data/sound_data_builder.cpp
index d71de7e..69a6871 100644
--- a/impl/oalpp/sound_data/sound_data_builder.cpp
+++ b/impl/oalpp/sound_data/sound_data_builder.cpp
@@ -17,6 +17,8 @@ oalpp::SoundData oalpp::SoundDataBuilder::create()
     return oalpp::SoundData { m_data, m_sampleRate, m_numberOfChannels };
 }
 
+// TODO does not need to be part of builder, extract into free function
+#if false
 oalpp::SoundDataBuilder& oalpp::SoundDataBuilder::toString(std::string& str)
 {
     str = "# Sound Data\n";
@@ -31,6 +33,8 @@ oalpp::SoundDataBuilder& oalpp::SoundDataBuilder::toString(std::string& str)
     return *this;
 }
 
+#endif
+
 oalpp::SoundDataBuilder& oalpp::SoundDataBuilder::withEffect(
     oalpp::effects::MonoEffectInterface& effect)
 {
diff --git a/impl/oalpp/sound_data/sound_data_builder.hpp b/impl/oalpp/sound_data/sound_data_builder.hpp
index f3b6184..8365bc0 100644
--- a/impl/oalpp/sound_data/sound_data_builder.hpp
+++ b/impl/oalpp/sound_data/sound_data_builder.hpp
@@ -10,13 +10,33 @@ namespace oalpp {
 
 class SoundDataBuilder {
 public:
+    /// create SoundData from the builder
+    /// \return SoundData object
     [[nodiscard]] SoundData create();
 
+    /// Load SoundData content from file. This will overwrite any previously stored SoundData
+    /// \param file path to the file
+    /// \return SoundDataBuilder object (fluent interface)
     [[nodiscard]] SoundDataBuilder& fromFile(std::string const& file);
-    [[nodiscard]] SoundDataBuilder& toString(std::string& str);
+
+    /// Apply an effect to the SoundData
+    /// \param effect effect to be applied
+    /// \return SoundDataBuilder object (fluent interface)
     [[nodiscard]] SoundDataBuilder& withEffect(oalpp::effects::MonoEffectInterface& effect);
+
+    /// Use only the left channel of the SoundData. If this is called on any non-stereo SoundData,
+    /// an exception is raised.
+    /// \return SoundDataBuilder object (fluent interface)
     [[nodiscard]] SoundDataBuilder& onlyLeftChannel();
+
+    /// Use only the right channel of the SoundData. If this is called on any non-stereo SoundData,
+    /// an exception is raised.
+    /// \return SoundDataBuilder object (fluent interface)
     [[nodiscard]] SoundDataBuilder& onlyRightChannel();
+
+    /// Convert a mono SoundData to a stereo SoundData. If this is called on any non-mono
+    /// SoundData, an exception is raised.
+    /// \return SoundDataBuilder object (fluent interface)
     [[nodiscard]] SoundDataBuilder& toStereo();
 
 private:
diff --git a/impl/oalpp/sound_data/sound_data_interface.hpp b/impl/oalpp/sound_data/sound_data_interface.hpp
index b4fd341..48404eb 100644
--- a/impl/oalpp/sound_data/sound_data_interface.hpp
+++ b/impl/oalpp/sound_data/sound_data_interface.hpp
@@ -8,12 +8,22 @@ namespace oalpp {
 
 class SoundDataInterface {
 public:
-    virtual ~SoundDataInterface() = default;
-
+    /// Get number of channels. This will return 1 for mono and 2 for stereo SoundData
+    /// \return number of channels
     virtual int getNumberOfChannels() const = 0;
+
+    /// Get sample rate
+    /// \return sample rate in Hz
     virtual int getSampleRate() const = 0;
+
+    /// access samples
+    /// \return reference to const data
     virtual std::vector<float> const& getSamples() const = 0;
 
+
+    // virtual destructor, avoid leaking data
+    virtual ~SoundDataInterface() = default;
+
     // avoid slicing via polymorphic copy or move
     SoundDataInterface(SoundDataInterface const& /*other*/) = delete;
     SoundDataInterface(SoundDataInterface&& /*other*/) = delete;
@@ -21,7 +31,7 @@ class SoundDataInterface {
     SoundDataInterface& operator=(SoundDataInterface&&) = delete;
 
 protected:
-    // allow default construction for derived classes
+    // allow default construction only for derived classes
     SoundDataInterface() = default;
 };