Improved the API documentation in the audio module

Removed the bufferSize parameter from sf::Music constructor

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1252 4e206d99-4929-0410-ac5d-dfc041789085

include/SFML/Audio/Music.hpp

@@ -42,51 +42,64 @@ namespace priv
 }
 
 ////////////////////////////////////////////////////////////
-/// Music defines a big sound played using streaming,
+/// \brief Streamed music played from an audio file
-/// so usually what we call a music :)
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Music : public SoundStream
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Construct the music with a buffer size
+    /// \brief Default constructor
-    ///
-    /// \param bufferSize : Size of the internal buffer, expressed in number of samples
-    ///                     (ie. size taken by the music in memory)
     ///
     ////////////////////////////////////////////////////////////
-    Music(std::size_t bufferSize = 44100);
+    Music();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~Music();
 
     ////////////////////////////////////////////////////////////
-    /// Open a music file (doesn't play it -- call Play() for that)
+    /// \brief Open a music from an audio file
     ///
-    /// \param filename : Path of the music file to open
+    /// This function doesn't start playing the music (call Play()
+    /// to do so).
+    /// Here is a complete list of all the supported audio formats:
+    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
     ///
-    /// \return True if loading has been successful
+    /// \param filename Path of the music file to open
+    ///
+    /// \return True if loading succeeded, false if it failed
+    ///
+    /// \see OpenFromMemory
     ///
     ////////////////////////////////////////////////////////////
     bool OpenFromFile(const std::string& filename);
 
     ////////////////////////////////////////////////////////////
-    /// Open a music file from memory (doesn't play it -- call Play() for that)
+    /// \brief Open a music from an audio file in memory
     ///
-    /// \param data :        Pointer to the file data in memory
+    /// This function doesn't start playing the music (call Play()
-    /// \param sizeInBytes : Size of the data to load, in bytes
+    /// to do so).
+    /// Here is a complete list of all the supported audio formats:
+    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
     ///
-    /// \return True if loading has been successful
+    /// \param data        Pointer to the file data in memory
+    /// \param sizeInBytes Size of the data to load, in bytes
+    ///
+    /// \return True if loading succeeded, false if it failed
+    ///
+    /// \see OpenFromFile
     ///
     ////////////////////////////////////////////////////////////
     bool OpenFromMemory(const char* data, std::size_t sizeInBytes);
 
     ////////////////////////////////////////////////////////////
-    /// Get the music duration
+    /// \brief Get the total duration of the music
     ///
     /// \return Music duration, in seconds
     ///
@@ -96,13 +109,22 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// /see SoundStream::OnGetData
+    /// \brief Request a new chunk of audio samples from the stream source
+    ///
+    /// This function fills the chunk from the next samples
+    /// to read from the audio file.
+    ///
+    /// \param data Chunk of data to fill
+    ///
+    /// \return True to continue playback, false to stop
     ///
     ////////////////////////////////////////////////////////////
     virtual bool OnGetData(Chunk& data);
 
     ////////////////////////////////////////////////////////////
-    /// /see SoundStream::OnSeek
+    /// \brief Change the current playing position in the stream source
+    ///
+    /// \param timeOffset New playing position, in seconds
     ///
     ////////////////////////////////////////////////////////////
     virtual void OnSeek(float timeOffset);
@@ -120,3 +142,48 @@ private :
 
 
 #endif // SFML_MUSIC_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Music
+///
+/// Musics are sounds that are streamed rather than completely
+/// loaded in memory. This is especially useful for compressed
+/// musics that usually take hundreds of MB when they are
+/// uncompressed: by streaming it instead of loading it entirely,
+/// you avoid saturating the memory and have almost no loading delay.
+///
+/// Apart from that, a sf::Music has almost the same features as
+/// the sf::SoundBuffer / sf::Sound pair: you can play/pause/stop
+/// it, request its parameters (channels, sample rate), change
+/// the way it is played (pitch, volume, 3D position, ...), etc.
+///
+/// As a sound stream, a music is played in its own thread in order
+/// not to block the rest of the program. This means that you can
+/// leave the music alone after calling Play(), it will manage itself
+/// very well.
+///
+/// Usage example:
+/// \code
+/// // Declare a new music
+/// sf::Music music;
+///
+/// // Open it from an audio file
+/// if (!music.OpenFromFile("music.ogg"))
+/// {
+///     // error...
+/// }
+///
+/// // Change some parameters
+/// music.SetPosition(0, 1, 10); // change its 3D position
+/// music.SetPitch(2);           // increase the pitch
+/// music.SetVolume(50);         // reduce the volume
+/// music.SetLoop(true);         // make it loop
+///
+/// // Play it
+/// music.Play();
+/// \endcode
+///
+/// \see sf::Sound, sf::SoundStream
+///
+////////////////////////////////////////////////////////////

include/SFML/Audio/SoundBuffer.hpp

@@ -37,139 +37,185 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// SoundBuffer is the low-level for loading and manipulating
+/// \brief Storage for audio samples defining a sound
-/// sound buffers
+///
 ////////////////////////////////////////////////////////////
 class SFML_API SoundBuffer : public Resource<SoundBuffer>
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     SoundBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Copy constructor
+    /// \brief Copy constructor
     ///
-    /// \param copy : Instance to copy
+    /// \param copy Instance to copy
     ///
     ////////////////////////////////////////////////////////////
     SoundBuffer(const SoundBuffer& copy);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~SoundBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Load the sound buffer from a file
+    /// \brief Load the sound buffer from a file
     ///
-    /// \param filename : Path of the sound file to load
+    /// Here is a complete list of all the supported audio formats:
+    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
     ///
-    /// \return True if loading has been successful
+    /// \param filename Path of the sound file to load
+    ///
+    /// \return True if loading succeeded, false if it failed
+    ///
+    /// \see LoadFromMemory, LoadFromSamples, SaveToFile
     ///
     ////////////////////////////////////////////////////////////
     bool LoadFromFile(const std::string& filename);
 
     ////////////////////////////////////////////////////////////
-    /// Load the sound buffer from a file in memory
+    /// \brief Load the sound buffer from a file in memory
     ///
-    /// \param data :        Pointer to the file data in memory
+    /// Here is a complete list of all the supported audio formats:
-    /// \param sizeInBytes : Size of the data to load, in bytes
+    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
     ///
-    /// \return True if loading has been successful
+    /// \param data        Pointer to the file data in memory
+    /// \param sizeInBytes Size of the data to load, in bytes
+    ///
+    /// \return True if loading succeeded, false if it failed
+    ///
+    /// \see LoadFromFile, LoadFromSamples, SaveToFile
     ///
     ////////////////////////////////////////////////////////////
     bool LoadFromMemory(const char* data, std::size_t sizeInBytes);
 
     ////////////////////////////////////////////////////////////
-    /// Load the sound buffer from an array of samples - assumed format for
+    /// \brief Load the sound buffer from an array of audio samples
-    /// samples is 16 bits signed integer
     ///
-    /// \param samples :       Pointer to the samples in memory
+    /// The assumed format of the audio samples is 16 bits signed integer
-    /// \param samplesCount :  Number of samples pointed by Samples
+    /// (sf::Int16).
-    /// \param channelsCount : Number of channels (1 = mono, 2 = stereo, ...)
-    /// \param sampleRate :    Frequency (number of samples to play per second)
     ///
-    /// \return True if loading has been successful
+    /// \param samples       Pointer to the array of samples in memory
+    /// \param samplesCount  Number of samples in the array
+    /// \param channelsCount Number of channels (1 = mono, 2 = stereo, ...)
+    /// \param sampleRate    Sample rate (number of samples to play per second)
+    ///
+    /// \return True if loading succeeded, false if it failed
+    ///
+    /// \see LoadFromFile, LoadFromMemory, SaveToFile
     ///
     ////////////////////////////////////////////////////////////
     bool LoadFromSamples(const Int16* samples, std::size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate);
 
     ////////////////////////////////////////////////////////////
-    /// Save the sound buffer to a file
+    /// \brief Save the sound buffer to an audio file
     ///
-    /// \param filename : Path of the sound file to write
+    /// Here is a complete list of all the supported audio formats:
+    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
     ///
-    /// \return True if saving has been successful
+    /// \param filename Path of the sound file to write
+    ///
+    /// \return True if saving succeeded, false if it failed
+    ///
+    /// \see LoadFromFile, LoadFromMemory, LoadFromSamples
     ///
     ////////////////////////////////////////////////////////////
     bool SaveToFile(const std::string& filename) const;
 
     ////////////////////////////////////////////////////////////
-    /// Return the sound samples
+    /// \brief Get the array of audio samples stored in the buffer
     ///
-    /// \return Pointer to the array of sound samples, in 16 bits signed integer format
+    /// The format of the returned samples is 16 bits signed integer
+    /// (sf::Int16). The total number of samples in this array
+    /// is given by the GetSamplesCount() function.
+    ///
+    /// \return Read-only pointer to the array of sound samples
+    ///
+    /// \see GetSamplesCount
     ///
     ////////////////////////////////////////////////////////////
     const Int16* GetSamples() const;
 
     ////////////////////////////////////////////////////////////
-    /// Return the samples count
+    /// \brief Get the number of samples stored in the buffer
+    ///
+    /// The array of samples can be accessed with the GetSamples()
+    /// function.
     ///
     /// \return Number of samples
     ///
+    /// \see GetSamples
+    ///
     ////////////////////////////////////////////////////////////
     std::size_t GetSamplesCount() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the sample rate
+    /// \brief Get the sample rate of the sound
     ///
-    /// \return Sound frequency (number of samples per second)
+    /// The sample rate is the number of samples played per second.
+    /// The higher, the better the quality (for example, 44100
+    /// samples/s is CD quality).
+    ///
+    /// \return Sample rate (number of samples per second)
+    ///
+    /// \see GetChannelsCount, GetDuration
     ///
     ////////////////////////////////////////////////////////////
     unsigned int GetSampleRate() const;
 
     ////////////////////////////////////////////////////////////
-    /// Return the number of channels (1 = mono, 2 = stereo, ...)
+    /// \brief Get the number of channels used by the sound
+    ///
+    /// If the sound is mono then the number ofchannels will
+    /// be 1, 2 for stereo, etc.
     ///
     /// \return Number of channels
     ///
+    /// \see GetSampleRate, GetDuration
+    ///
     ////////////////////////////////////////////////////////////
     unsigned int GetChannelsCount() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the sound duration
+    /// \brief Get the total duration of the sound
     ///
     /// \return Sound duration, in seconds
     ///
+    /// \see GetSampleRate, GetChannelsCount
+    ///
     ////////////////////////////////////////////////////////////
     float GetDuration() const;
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator
+    /// \brief Overload of assignment operator
     ///
-    /// \param other : Instance to assign
+    /// \param right Instance to assign
     ///
-    /// \return Reference to the sound buffer
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
-    SoundBuffer& operator =(const SoundBuffer& other);
+    SoundBuffer& operator =(const SoundBuffer& right);
 
 private :
 
     friend class Sound;
 
     ////////////////////////////////////////////////////////////
-    /// Update the internal buffer with the audio samples
+    /// \brief Update the internal buffer with the cached audio samples
     ///
-    /// \param channelsCount : Number of channels
+    /// \param channelsCount Number of channels
-    /// \param sampleRate :    Sample rate
+    /// \param sampleRate    Sample rate (number of samples per second)
     ///
-    /// \return True on success
+    /// \return True on success, false if any error happened
     ///
     ////////////////////////////////////////////////////////////
     bool Update(unsigned int channelsCount, unsigned int sampleRate);
@@ -186,3 +232,70 @@ private :
 
 
 #endif // SFML_SOUNDBUFFER_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::SoundBuffer
+///
+/// A sound buffer holds the data of a sound, which is
+/// an array of audio samples. A sample is a 16 bits signed integer
+/// that defines the amplitude of the sound at a given time.
+/// The sound is then restituted by playing these samples at
+/// a high rate (for example, 44100 samples per second is the
+/// standard rate used for playing CDs). In short, audio samples
+/// are like image pixels, and a sf::SoundBuffer is similar to
+/// a sf::Image.
+///
+/// A sound buffer can be loaded from a file (see LoadFromFile()
+/// for the complete list of supported formats), from memory
+/// or directly from an array of samples. It can also be saved
+/// back to a file.
+///
+/// Sound buffers alone are not very useful: they hold the audio data
+/// but cannot be played. To do so, you need to use the sf::Sound class,
+/// which provides functions to play/pause/stop the sound as well as
+/// changing the way it is outputted (volume, pitch, 3D position, ...).
+/// This separation allows more flexibility and better performances:
+/// indeed a sf::SoundBuffer is a heavy resource, and any operation on it
+/// is slow (often too slow for real-time applications). On the other
+/// side, a sf::Sound is a lightweight object, which can use the audio data
+/// of a sound buffer and change the way it is played without actually
+/// modifying that data. Note that it is also possible to bind
+/// several sf::Sound instances to the same sf::SoundBuffer.
+///
+/// It is important to note that the sf::Sound instance doesn't
+/// copy the buffer that it uses, it only keeps a reference to it.
+/// Thus, a sf::SoundBuffer must not be destructed while it is
+/// used by a sf::Sound (i.e. never write a function that
+/// uses a local sf::SoundBuffer instance for loading a sound).
+///
+/// Usage example:
+/// \code
+/// // Declare a new sound buffer
+/// sf::SoundBuffer buffer;
+/// 
+/// // Load it from a file
+/// if (!buffer.LoadFromFile("sound.wav"))
+/// {
+///     // error...
+/// }
+/// 
+/// // Create a sound source and bind it to the buffer
+/// sf::Sound sound1;
+/// sound1.SetBuffer(buffer);
+/// 
+/// // Play the sound
+/// sound1.Play();
+/// 
+/// // Create another sound source bound to the same buffer
+/// sf::Sound sound2;
+/// sound2.SetBuffer(buffer);
+///
+/// // Play it with a higher pitch -- the first sound remains unchanged
+/// sound2.SetPitch(2);
+/// sound2.Play();
+/// \endcode
+///
+/// \see sf::Sound, sf::SoundBufferRecorder
+///
+////////////////////////////////////////////////////////////

include/SFML/System/Thread.hpp

@@ -42,12 +42,13 @@ namespace priv
 
 ////////////////////////////////////////////////////////////
 /// \brief Utility class to manipulate threads
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Thread : NonCopyable
 {
 public :
 
-    typedef void (*FuncType)(void*); ///< Type of functions that can be used as thread entry points
+    typedef void (*FuncType)(void*); // Type of functions that can be used as thread entry points
 
     ////////////////////////////////////////////////////////////
     /// \brief Construct the thread from a function pointer
@@ -194,4 +195,6 @@ private :
 /// from multiple threads at the same time. To prevent this
 /// kind of situations, you can use mutexes (see sf::Mutex).
 ///
+/// \see sf::Mutex
+///
 ////////////////////////////////////////////////////////////

src/SFML/Audio/Music.cpp

@@ -36,19 +36,14 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Construct the music with a buffer size
+Music::Music() :
-////////////////////////////////////////////////////////////
-Music::Music(std::size_t bufferSize) :
 myFile    (new priv::SoundFile),
-myDuration(0.f),
+myDuration(0.f)
-mySamples (bufferSize)
 {
 
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 Music::~Music()
 {
@@ -59,8 +54,6 @@ Music::~Music()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Open a music file (doesn't play it -- call Play() for that)
 ////////////////////////////////////////////////////////////
 bool Music::OpenFromFile(const std::string& filename)
 {
@@ -77,6 +70,9 @@ bool Music::OpenFromFile(const std::string& filename)
     // Compute the duration
     myDuration = static_cast<float>(myFile->GetSamplesCount()) / myFile->GetSampleRate() / myFile->GetChannelsCount();
 
+    // Resize the internal buffer so that it can contain 1 second of audio samples
+    mySamples.resize(myFile->GetSampleRate());
+
     // Initialize the stream
     Initialize(myFile->GetChannelsCount(), myFile->GetSampleRate());
 
@@ -84,8 +80,6 @@ bool Music::OpenFromFile(const std::string& filename)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Open a music file from memory (doesn't play it -- call Play() for that)
 ////////////////////////////////////////////////////////////
 bool Music::OpenFromMemory(const char* data, std::size_t sizeInBytes)
 {
@@ -100,7 +94,10 @@ bool Music::OpenFromMemory(const char* data, std::size_t sizeInBytes)
     }
 
     // Compute the duration
-    myDuration = static_cast<float>(myFile->GetSamplesCount()) / myFile->GetSampleRate();
+    myDuration = static_cast<float>(myFile->GetSamplesCount()) / myFile->GetSampleRate() / myFile->GetChannelsCount();
+
+    // Resize the internal buffer so that it can contain 1 second of audio samples
+    mySamples.resize(myFile->GetSampleRate());
 
     // Initialize the stream
     Initialize(myFile->GetChannelsCount(), myFile->GetSampleRate());
@@ -109,8 +106,6 @@ bool Music::OpenFromMemory(const char* data, std::size_t sizeInBytes)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sound duration
 ////////////////////////////////////////////////////////////
 float Music::GetDuration() const
 {
@@ -118,8 +113,6 @@ float Music::GetDuration() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see SoundStream::OnGetData
 ////////////////////////////////////////////////////////////
 bool Music::OnGetData(SoundStream::Chunk& data)
 {

src/SFML/Audio/Sound.cpp

@@ -33,8 +33,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Sound::Sound()
 {
     ALCheck(alGenSources(1, &mySource));
@@ -42,8 +40,6 @@ Sound::Sound()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the sound from its parameters
 ////////////////////////////////////////////////////////////
 Sound::Sound(const SoundBuffer& buffer, bool loop, float pitch, float volume, const Vector3f& position) :
 myBuffer(NULL)
@@ -58,8 +54,6 @@ myBuffer(NULL)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy constructor
 ////////////////////////////////////////////////////////////
 Sound::Sound(const Sound& copy) :
 myBuffer(NULL)
@@ -78,8 +72,6 @@ myBuffer(NULL)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 Sound::~Sound()
 {
@@ -95,8 +87,6 @@ Sound::~Sound()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Play the sound
 ////////////////////////////////////////////////////////////
 void Sound::Play()
 {
@@ -104,8 +94,6 @@ void Sound::Play()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Pause the sound
 ////////////////////////////////////////////////////////////
 void Sound::Pause()
 {
@@ -113,8 +101,6 @@ void Sound::Pause()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop the sound
 ////////////////////////////////////////////////////////////
 void Sound::Stop()
 {
@@ -122,8 +108,6 @@ void Sound::Stop()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the source buffer
 ////////////////////////////////////////////////////////////
 void Sound::SetBuffer(const SoundBuffer& buffer)
 {
@@ -132,8 +116,6 @@ void Sound::SetBuffer(const SoundBuffer& buffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the sound loop state
 ////////////////////////////////////////////////////////////
 void Sound::SetLoop(bool Loop)
 {
@@ -141,8 +123,6 @@ void Sound::SetLoop(bool Loop)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the sound pitch
 ////////////////////////////////////////////////////////////
 void Sound::SetPitch(float pitch)
 {
@@ -150,17 +130,12 @@ void Sound::SetPitch(float pitch)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the sound volume
 ////////////////////////////////////////////////////////////
 void Sound::SetVolume(float volume)
 {
     ALCheck(alSourcef(mySource, AL_GAIN, volume * 0.01f));
 }
 
-////////////////////////////////////////////////////////////
-/// Set the sound position (take 3 values).
-/// The default position is (0, 0, 0)
 ////////////////////////////////////////////////////////////
 void Sound::SetPosition(float x, float y, float z)
 {
@@ -168,9 +143,6 @@ void Sound::SetPosition(float x, float y, float z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the sound position (take a 3D vector).
-/// The default position is (0, 0, 0)
 ////////////////////////////////////////////////////////////
 void Sound::SetPosition(const Vector3f& position)
 {
@@ -178,10 +150,6 @@ void Sound::SetPosition(const Vector3f& position)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make the sound's position relative to the listener's
-/// position, or absolute.
-/// The default value is false (absolute)
 ////////////////////////////////////////////////////////////
 void Sound::SetRelativeToListener(bool relative)
 {
@@ -189,10 +157,6 @@ void Sound::SetRelativeToListener(bool relative)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
-/// the listener will hear the sound at its maximum volume.
-/// The default minimum distance is 1.0
 ////////////////////////////////////////////////////////////
 void Sound::SetMinDistance(float distance)
 {
@@ -200,10 +164,6 @@ void Sound::SetMinDistance(float distance)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the attenuation factor - the higher the attenuation, the
-/// more the sound will be attenuated with distance from listener.
-/// The default attenuation factor 1.0
 ////////////////////////////////////////////////////////////
 void Sound::SetAttenuation(float attenuation)
 {
@@ -211,8 +171,6 @@ void Sound::SetAttenuation(float attenuation)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the current playing position of the sound
 ////////////////////////////////////////////////////////////
 void Sound::SetPlayingOffset(float timeOffset)
 {
@@ -220,8 +178,6 @@ void Sound::SetPlayingOffset(float timeOffset)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the source buffer
 ////////////////////////////////////////////////////////////
 const SoundBuffer* Sound::GetBuffer() const
 {
@@ -229,8 +185,6 @@ const SoundBuffer* Sound::GetBuffer() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not the sound is looping
 ////////////////////////////////////////////////////////////
 bool Sound::GetLoop() const
 {
@@ -241,8 +195,6 @@ bool Sound::GetLoop() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the pitch
 ////////////////////////////////////////////////////////////
 float Sound::GetPitch() const
 {
@@ -253,8 +205,6 @@ float Sound::GetPitch() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the volume
 ////////////////////////////////////////////////////////////
 float Sound::GetVolume() const
 {
@@ -265,8 +215,6 @@ float Sound::GetVolume() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sound position
 ////////////////////////////////////////////////////////////
 Vector3f Sound::GetPosition() const
 {
@@ -277,9 +225,6 @@ Vector3f Sound::GetPosition() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the sound's position is relative to the listener's
-/// position, or if it's absolute
 ////////////////////////////////////////////////////////////
 bool Sound::IsRelativeToListener() const
 {
@@ -290,8 +235,6 @@ bool Sound::IsRelativeToListener() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the minimum distance
 ////////////////////////////////////////////////////////////
 float Sound::GetMinDistance() const
 {
@@ -302,8 +245,6 @@ float Sound::GetMinDistance() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the attenuation factor
 ////////////////////////////////////////////////////////////
 float Sound::GetAttenuation() const
 {
@@ -314,8 +255,6 @@ float Sound::GetAttenuation() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current playing position of the sound
 ////////////////////////////////////////////////////////////
 float Sound::GetPlayingOffset() const
 {
@@ -326,8 +265,6 @@ float Sound::GetPlayingOffset() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the status of the sound (stopped, paused, playing)
 ////////////////////////////////////////////////////////////
 Sound::Status Sound::GetStatus() const
 {
@@ -346,8 +283,6 @@ Sound::Status Sound::GetStatus() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
 ////////////////////////////////////////////////////////////
 Sound& Sound::operator =(const Sound& other)
 {

src/SFML/Audio/SoundBuffer.cpp

@@ -36,8 +36,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 SoundBuffer::SoundBuffer() :
 myBuffer  (0),
 myDuration(0.f)
@@ -47,8 +45,6 @@ myDuration(0.f)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy constructor
 ////////////////////////////////////////////////////////////
 SoundBuffer::SoundBuffer(const SoundBuffer& copy) :
 Resource<SoundBuffer>(copy),
@@ -64,8 +60,6 @@ myDuration           (copy.myDuration)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 SoundBuffer::~SoundBuffer()
 {
@@ -74,8 +68,6 @@ SoundBuffer::~SoundBuffer()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load the sound buffer from a file
 ////////////////////////////////////////////////////////////
 bool SoundBuffer::LoadFromFile(const std::string& filename)
 {
@@ -107,8 +99,6 @@ bool SoundBuffer::LoadFromFile(const std::string& filename)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load the sound buffer from a file in memory
 ////////////////////////////////////////////////////////////
 bool SoundBuffer::LoadFromMemory(const char* data, std::size_t sizeInBytes)
 {
@@ -140,9 +130,6 @@ bool SoundBuffer::LoadFromMemory(const char* data, std::size_t sizeInBytes)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load the sound buffer from an array of samples  - assumed format for
-/// samples is 16 bits signed integer
 ////////////////////////////////////////////////////////////
 bool SoundBuffer::LoadFromSamples(const Int16* samples, std::size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate)
 {
@@ -169,8 +156,6 @@ bool SoundBuffer::LoadFromSamples(const Int16* samples, std::size_t samplesCount
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save the sound buffer to a file
 ////////////////////////////////////////////////////////////
 bool SoundBuffer::SaveToFile(const std::string& filename) const
 {
@@ -190,8 +175,6 @@ bool SoundBuffer::SaveToFile(const std::string& filename) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the sound samples
 ////////////////////////////////////////////////////////////
 const Int16* SoundBuffer::GetSamples() const
 {
@@ -199,8 +182,6 @@ const Int16* SoundBuffer::GetSamples() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the samples count
 ////////////////////////////////////////////////////////////
 std::size_t SoundBuffer::GetSamplesCount() const
 {
@@ -208,8 +189,6 @@ std::size_t SoundBuffer::GetSamplesCount() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sample rate
 ////////////////////////////////////////////////////////////
 unsigned int SoundBuffer::GetSampleRate() const
 {
@@ -220,8 +199,6 @@ unsigned int SoundBuffer::GetSampleRate() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of channels (1 = mono, 2 = stereo, ...)
 ////////////////////////////////////////////////////////////
 unsigned int SoundBuffer::GetChannelsCount() const
 {
@@ -232,8 +209,6 @@ unsigned int SoundBuffer::GetChannelsCount() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sound duration
 ////////////////////////////////////////////////////////////
 float SoundBuffer::GetDuration() const
 {
@@ -241,8 +216,6 @@ float SoundBuffer::GetDuration() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
 ////////////////////////////////////////////////////////////
 SoundBuffer& SoundBuffer::operator =(const SoundBuffer& other)
 {
@@ -256,8 +229,6 @@ SoundBuffer& SoundBuffer::operator =(const SoundBuffer& other)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Update the internal buffer with the audio samples
 ////////////////////////////////////////////////////////////
 bool SoundBuffer::Update(unsigned int channelsCount, unsigned int sampleRate)
 {