Implement documentation on sound class.

include/ReMixer/sound.h

@@ -8,38 +8,90 @@
 #include <iterator>
 #include <vorbis/vorbisfile.h>
 
-namespace ReMixer
-{
-    class Sound {
-    private:
-        std::vector<char> audio_data;
-        uint sample_rate;
-        StreamMode stream_mode;
-    public:
+namespace ReMixer {
+    // TODO: Implement support for loading Linear-PCM if necessary.
+    // TODO: Correctly handle different 'sample-depths'. PCM Samples can be encoded at 8, 16, 20, or 24 bits-per-sample.
 
+    /// The sound class contains a raw audio data buffer in Pulse-Code Modulated form.
+    class Sound {
+    public:
+        /// The default constructor for a Sound object is intentionally left undefined.
+        /// It is intended that you use the static constructors below to load Sound objects.
+        Sound() = default;
+
+        /// Returns a Sound object loaded from a OGG Vorbis file, usually with an .ogg extension.
+        /// The sample rate and channel mode will be read from the vorbisfile header.
+        /// @param file_name The full path relative to the executable in which the file is located.
+        /// @see https://en.wikipedia.org/wiki/Vorbis
+        /// @see LoadOGGVorbisFile().
         static Sound FromOGGVorbisFile(const std::filesystem::path& file_name);
+
+        /// Returns a sound object loaded from a file containing raw PCM sound data in binary form.
+        /// @param file_name The full path relative to the executable in which the file is located.
+        /// @param sampleRate A uint that indicates the samples-per-second of the sound data.
+        /// @param streamMode An enum representing the number of channels.
+        /// @see https://en.wikipedia.org/wiki/Pulse-code_modulation.
+        /// @see FromPCMBuffer(), LoadPCMFile(), enum StreamMode.
         static Sound FromPCMFile(const std::filesystem::path& file_name, uint sampleRate = 44.1_kHz, StreamMode streamMode = StreamMode::STEREO);
+
+        /// Returns a sound object loaded from a byte-buffer containing raw PCM sound data.
+        /// @param buffer The byte buffer that will be copied into this sound object.
+        /// @param sampleRate A uint that indicates the samples-per-second of the sound data.
+        /// @param streamMode An enum representing the number of channels.
+        /// @see https://en.wikipedia.org/wiki/Pulse-code_modulation.
         static Sound FromPCMBuffer(std::vector<char> buffer, uint sampleRate = 44.1_kHz, StreamMode streamMode = StreamMode::STEREO);
 
-
+        /// Fills this sound instance with data from a file encoded with OGG vorbis, usually with an .ogg extension.
+        /// @param file_name The full path relative to the executable in which the file is located.
+        /// @see https://en.wikipedia.org/wiki/Vorbis
+        /// @see FromOGGVorbisFile().
         void LoadOGGVorbisFile(const std::filesystem::path& file_name);
+
+        /// Fills this sound instance with data from a file containing raw PCM sound data.
+        /// @param file_name The full path relative to the executable in which the file is located.
+        /// @param sampleRate A uint that indicates the samples-per-second of the sound data.
+        /// @param streamMode An enum representing the number of channels.
+        /// @see https://en.wikipedia.org/wiki/Pulse-code_modulation.
         void LoadPCMFile(const std::filesystem::path& file_name, uint sampleRate = 44.1_kHz, StreamMode streamMode = StreamMode::STEREO);
+
+        /// Fills this sound instance with data from a byte-buffer containing raw PCM sound data.
+        /// @param buffer The byte buffer that will be copied into this sound object.
+        /// @param sampleRate A uint that indicates the samples-per-second of the sound data.
+        /// @param streamMode An enum representing the number of channels.
+        /// @see https://en.wikipedia.org/wiki/Pulse-code_modulation.
         void LoadPCMBuffer(std::vector<char> buffer, uint sampleRate = 44.1_kHz, StreamMode streamMode = StreamMode::STEREO);
 
-        unsigned int DataSize() const { return audio_data.size();};
+        /// Returns the sample count of the sound.
+        unsigned int SampleCount() const { return audio_data.size();};
+
+        /// Returns the amount of bytes the sounds' data occupies.
+        uint DataSizeInBytes() const;
+
+        /// Returns the samples-per-second of this sound.
+        uint SampleRate() const { return sample_rate;}
+
         char* ptr() { return audio_data.data();}
         [[nodiscard]] const char* ptr() const { return audio_data.data();}
-        Sound() = default;
+
+
+
+
+    public:
+
+    private:
+        uint sample_rate;
+        std::vector<char> audio_data;
+        StreamMode stream_mode;
     };
 
     /// Class that holds a short sound that can fit in memory and requires no latency. (i.e. footsteps or gun shots).
-    class SFX {
-
+    class SFX : public Sound {
+        // TODO: Implement SFX class.
     };
 
     /// Music class is for longer sounds that should be streamed in.
-    class Music {
-
+    class Music : public Sound {
+        // TODO: Implement Music class.
     };
 }