Add documentation

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

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)
 {

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:

impl/oalpp/sound_data/sound_data_interface.hpp

@@ -8,20 +8,30 @@ 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;
     SoundDataInterface& operator=(SoundDataInterface const&) = delete;
     SoundDataInterface& operator=(SoundDataInterface&&) = delete;
 
 protected:
-    // allow default construction for derived classes
+    // allow default construction only for derived classes
     SoundDataInterface() = default;
 };