Improved API documentation (copied from SFML)

src/SFML/Audio/Sound.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new sound
 ////////////////////////////////////////////////////////////
 sfSound* sfSound_Create(void)
 {
@@ -39,8 +37,6 @@ sfSound* sfSound_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy an existing sound
 ////////////////////////////////////////////////////////////
 sfSound* sfSound_Copy(sfSound* sound)
 {
@@ -50,8 +46,6 @@ sfSound* sfSound_Copy(sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing sound
 ////////////////////////////////////////////////////////////
 void sfSound_Destroy(sfSound* sound)
 {
@@ -59,8 +53,6 @@ void sfSound_Destroy(sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Start playing a sound
 ////////////////////////////////////////////////////////////
 void sfSound_Play(sfSound* sound)
 {
@@ -68,8 +60,6 @@ void sfSound_Play(sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Pause a sound
 ////////////////////////////////////////////////////////////
 void sfSound_Pause(sfSound* sound)
 {
@@ -77,8 +67,6 @@ void sfSound_Pause(sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop playing a sound
 ////////////////////////////////////////////////////////////
 void sfSound_Stop(sfSound* sound)
 {
@@ -86,8 +74,6 @@ void sfSound_Stop(sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Bind a sound buffer to a sound
 ////////////////////////////////////////////////////////////
 void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer)
 {
@@ -99,8 +85,6 @@ void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sound buffer bound to a sound
 ////////////////////////////////////////////////////////////
 const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound)
 {
@@ -110,8 +94,6 @@ const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set a sound loop state
 ////////////////////////////////////////////////////////////
 void sfSound_SetLoop(sfSound* sound, sfBool loop)
 {
@@ -119,8 +101,6 @@ void sfSound_SetLoop(sfSound* sound, sfBool loop)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not a sound is looping
 ////////////////////////////////////////////////////////////
 sfBool sfSound_GetLoop(const sfSound* sound)
 {
@@ -128,8 +108,6 @@ sfBool sfSound_GetLoop(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the status of a sound (stopped, paused, playing)
 ////////////////////////////////////////////////////////////
 sfSoundStatus sfSound_GetStatus(const sfSound* sound)
 {
@@ -139,8 +117,6 @@ sfSoundStatus sfSound_GetStatus(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the pitch of a sound
 ////////////////////////////////////////////////////////////
 void sfSound_SetPitch(sfSound* sound, float pitch)
 {
@@ -148,8 +124,6 @@ void sfSound_SetPitch(sfSound* sound, float pitch)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the volume of a sound
 ////////////////////////////////////////////////////////////
 void sfSound_SetVolume(sfSound* sound, float volume)
 {
@@ -157,8 +131,6 @@ void sfSound_SetVolume(sfSound* sound, float volume)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the position of a sound
 ////////////////////////////////////////////////////////////
 void sfSound_SetPosition(sfSound* sound, float x, float y, float z)
 {
@@ -166,10 +138,6 @@ void sfSound_SetPosition(sfSound* sound, float x, float y, float z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make the sound's position relative to the listener's
-/// position, or absolute.
-/// The default value is false (absolute)
 ////////////////////////////////////////////////////////////
 void sfSound_SetRelativeToListener(sfSound* sound, sfBool relative)
 {
@@ -177,10 +145,6 @@ void sfSound_SetRelativeToListener(sfSound* sound, sfBool 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 sfSound_SetMinDistance(sfSound* sound, float distance)
 {
@@ -188,10 +152,6 @@ void sfSound_SetMinDistance(sfSound* sound, 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 is 1.0
 ////////////////////////////////////////////////////////////
 void sfSound_SetAttenuation(sfSound* sound, float attenuation)
 {
@@ -199,8 +159,6 @@ void sfSound_SetAttenuation(sfSound* sound, float attenuation)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the current playing position of a sound
 ////////////////////////////////////////////////////////////
 void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset)
 {
@@ -208,8 +166,6 @@ void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the pitch of a sound
 ////////////////////////////////////////////////////////////
 float sfSound_GetPitch(const sfSound* sound)
 {
@@ -217,8 +173,6 @@ float sfSound_GetPitch(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the volume of a sound
 ////////////////////////////////////////////////////////////
 float sfSound_GetVolume(const sfSound* sound)
 {
@@ -226,8 +180,6 @@ float sfSound_GetVolume(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the position of a sound
 ////////////////////////////////////////////////////////////
 void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z)
 {
@@ -240,9 +192,6 @@ void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the sound's position is relative to the listener's
-/// position, or if it's absolute
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound)
 {
@@ -250,8 +199,6 @@ CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the minimum distance of a sound
 ////////////////////////////////////////////////////////////
 float sfSound_GetMinDistance(const sfSound* sound)
 {
@@ -259,8 +206,6 @@ float sfSound_GetMinDistance(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a sound
 ////////////////////////////////////////////////////////////
 float sfSound_GetAttenuation(const sfSound* sound)
 {
@@ -268,8 +213,6 @@ float sfSound_GetAttenuation(const sfSound* sound)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current playing position of a sound
 ////////////////////////////////////////////////////////////
 sfUint32 sfSound_GetPlayingOffset(const sfSound* sound)
 {