Improved API documentation (copied from SFML)

include/SFML/Audio/Listener.h

@@ -32,15 +32,19 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Change the global volume of all the sounds
+/// \brief Change the global volume of all the sounds and musics
 ///
-/// \param volume : New global volume, in the range [0, 100]
+/// The volume is a number between 0 and 100; it is combined with
+/// the individual volume of each sound / music.
+/// The default value for the volume is 100 (maximum).
+///
+/// \param volume New global volume, in the range [0, 100]
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfListener_SetGlobalVolume(float volume);
 
 ////////////////////////////////////////////////////////////
-/// Get the current value of the global volume of all the sounds
+/// \brief Get the current value of the global volume
 ///
 /// \return Current global volume, in the range [0, 100]
 ///
@@ -48,41 +52,48 @@ CSFML_API void sfListener_SetGlobalVolume(float volume);
 CSFML_API float sfListener_GetGlobalVolume(void);
 
 ////////////////////////////////////////////////////////////
-/// Change the position of the listener
+/// \brief Set the position of the listener in the scene
 ///
-/// \param x : X position of the listener in the world
+/// The default listener's position is (0, 0, 0).
-/// \param y : Y position of the listener in the world
+///
-/// \param z : Z position of the listener in the world
+/// \param x X coordinate of the listener's position
+/// \param y Y coordinate of the listener's position
+/// \param z Z coordinate of the listener's position
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfListener_SetPosition(float x, float y, float z);
 
 ////////////////////////////////////////////////////////////
-/// Get the current position of the listener
+/// \brief Get the current position of the listener in the scene
 ///
-/// \param x : X position of the listener in the world
+/// \param x X coordinate of the listener's position
-/// \param y : Y position of the listener in the world
+/// \param y Y coordinate of the listener's position
-/// \param z : Z position of the listener in the world
+/// \param z Z coordinate of the listener's position
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfListener_GetPosition(float* x, float* y, float* z);
 
 ////////////////////////////////////////////////////////////
-/// Change the orientation of the listener
+/// \brief Set the orientation of the listener in the scene
 ///
-/// \param x : X component of the listener's direction
+/// The orientation defines the 3D axes of the listener
-/// \param y : Y component of the listener's direction
+/// (left, up, front) in the scene. The orientation vector
-/// \param z : Z component of the listener's direction
+/// doesn't have to be normalized.
+/// The default listener's orientation is (0, 0, -1).
+///
+/// \param x X coordinate of the listener's orientation
+/// \param y Y coordinate of the listener's orientation
+/// \param z Z coordinate of the listener's orientation
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfListener_SetDirection(float x, float y, float z);
 
 ////////////////////////////////////////////////////////////
-/// Get the current orientation of the listener
+/// \brief Get the current orientation of the listener in the scene
 ///
-/// \param x : X component of the listener's direction
+/// \param x X coordinate of the listener's orientation
-/// \param y : Y component of the listener's direction
+/// \param y Y coordinate of the listener's orientation
-/// \param z : Z component of the listener's direction
+/// \param z Z coordinate of the listener's orientation
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfListener_GetDirection(float* x, float* y, float* z);

include/SFML/Audio/Music.h

@@ -36,9 +36,15 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new music and load it from a file
+/// \brief Create a new music and load it from a file
 ///
-/// \param filename : Path of the music file to open
+/// This function doesn't start playing the music (call
+/// sfMusic_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.
+///
+/// \param filename Path of the music file to open
 ///
 /// \return A new sfMusic object (NULL if failed)
 ///
@@ -46,10 +52,16 @@
 CSFML_API sfMusic* sfMusic_CreateFromFile(const char* filename);
 
 ////////////////////////////////////////////////////////////
-/// Create a new music and load it from a file in memory
+/// \brief Create a new music and load it from a file in memory
 ///
-/// \param data :        Pointer to the file data in memory
+/// This function doesn't start playing the music (call
-/// \param sizeInBytes : Size of the data to load, in bytes
+/// sfMusic_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.
+///
+/// \param data        Pointer to the file data in memory
+/// \param sizeInBytes Size of the data to load, in bytes
 ///
 /// \return A new sfMusic object (NULL if failed)
 ///
@@ -57,9 +69,15 @@ CSFML_API sfMusic* sfMusic_CreateFromFile(const char* filename);
 CSFML_API sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes);
 
 ////////////////////////////////////////////////////////////
-/// Create a new music and load it from a custom stream
+/// \brief Create a new music and load it from a custom stream
 ///
-/// \param stream : Source stream to read from
+/// This function doesn't start playing the music (call
+/// sfMusic_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.
+///
+/// \param stream Source stream to read from
 ///
 /// \return A new sfMusic object (NULL if failed)
 ///
@@ -67,26 +85,31 @@ CSFML_API sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes
 CSFML_API sfMusic* sfMusic_CreateFromStream(sfInputStream* stream);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing music
+/// \brief Destroy a music
 ///
-/// \param music : Music to delete
+/// \param music Music to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_Destroy(sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Set a music loop state
+/// \brief Set whether or not a music should loop after reaching the end
 ///
-/// \param music : Music to set the loop state
+/// If set, the music will restart from beginning after
-/// \param loop :  sfTrue to play in loop, sfFalse to play once
+/// reaching the end and so on, until it is stopped or
+/// sfMusic_SetLoop(music, sfFalse) is called.
+/// The default looping state for musics is false.
+///
+/// \param music Music object
+/// \param loop  sfTrue to play in loop, sfFalse to play once
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetLoop(sfMusic* music, sfBool loop);
 
 ////////////////////////////////////////////////////////////
-/// Tell whether or not a music is looping
+/// \brief Tell whether or not a music is in loop mode
 ///
-/// \param music : Music to get the loop state from
+/// \param music Music object
 ///
 /// \return sfTrue if the music is looping, sfFalse otherwise
 ///
@@ -94,9 +117,9 @@ CSFML_API void sfMusic_SetLoop(sfMusic* music, sfBool loop);
 CSFML_API sfBool sfMusic_GetLoop(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get a music duration
+/// \brief Get the total duration of a music
 ///
-/// \param music : Music to get the duration from
+/// \param music Music object
 ///
 /// \return Music duration, in milliseconds
 ///
@@ -104,33 +127,48 @@ CSFML_API sfBool sfMusic_GetLoop(const sfMusic* music);
 CSFML_API sfUint32 sfMusic_GetDuration(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Start playing a music
+/// \brief Start or resume playing a music
 ///
-/// \param music : Music to play
+/// This function starts the music if it was stopped, resumes
+/// it if it was paused, and restarts it from beginning if it
+/// was it already playing.
+/// This function uses its own thread so that it doesn't block
+/// the rest of the program while the music is played.
+///
+/// \param music Music object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_Play(sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Pause a music
+/// \brief Pause a music
 ///
-/// \param music : Music to pause
+/// This function pauses the music if it was playing,
+/// otherwise (music already paused or stopped) it has no effect.
+///
+/// \param music Music object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_Pause(sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Stop playing a music
+/// \brief Stop playing a music
 ///
-/// \param music : Music to stop
+/// This function stops the music if it was playing or paused,
+/// and does nothing if it was already stopped.
+/// It also resets the playing position (unlike sfMusic_Pause).
+///
+/// \param music Music object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_Stop(sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Return the number of channels of a music (1 = mono, 2 = stereo)
+/// \brief Return the number of channels of a music
 ///
-/// \param music : Music to get the channels count from
+/// 1 channel means a mono sound, 2 means stereo, etc.
+///
+/// \param music Music object
 ///
 /// \return Number of channels
 ///
@@ -138,29 +176,32 @@ CSFML_API void sfMusic_Stop(sfMusic* music);
 CSFML_API unsigned int sfMusic_GetChannelsCount(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the stream sample rate of a music
+/// \brief Get the sample rate of a music
 ///
-/// \param music : Music to get the sample rate from
+/// The sample rate is the number of audio samples played per
+/// second. The higher, the better the quality.
 ///
-/// \return Stream frequency (number of samples per second)
+/// \param music Music object
+///
+/// \return Sample rate, in number of samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfMusic_GetSampleRate(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the status of a music (stopped, paused, playing)
+/// \brief Get the current status of a music (stopped, paused, playing)
 ///
-/// \param music : Music to get the status from
+/// \param music Music object
 ///
-/// \return Current status of the sound
+/// \return Current status
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSoundStatus sfMusic_GetStatus(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the current playing position of a music
+/// \brief Get the current playing position of a music
 ///
-/// \param music : Music to get the position from
+/// \param music Music object
 ///
 /// \return Current playing position, in milliseconds
 ///
@@ -168,112 +209,144 @@ CSFML_API sfSoundStatus sfMusic_GetStatus(const sfMusic* music);
 CSFML_API sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Set the pitch of a music
+/// \brief Set the pitch of a music
 ///
-/// \param music : Music to modify
+/// The pitch represents the perceived fundamental frequency
-/// \param pitch : New pitch
+/// of a sound; thus you can make a music more acute or grave
+/// by changing its pitch. A side effect of changing the pitch
+/// is to modify the playing speed of the music as well.
+/// The default value for the pitch is 1.
+///
+/// \param music Music object
+/// \param pitch New pitch to apply to the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetPitch(sfMusic* music, float pitch);
 
 ////////////////////////////////////////////////////////////
-/// Set the volume of a music
+/// \brief Set the volume of a music
 ///
-/// \param music :  Music to modify
+/// The volume is a value between 0 (mute) and 100 (full volume).
-/// \param volume : Volume (in range [0, 100])
+/// The default value for the volume is 100.
+///
+/// \param music  Music object
+/// \param volume Volume of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetVolume(sfMusic* music, float volume);
 
 ////////////////////////////////////////////////////////////
-/// Set the position of a music
+/// \brief Set the 3D position of a music in the audio scene
 ///
-/// \param music : Music to modify
+/// Only musics with one channel (mono musics) can be
-/// \param x :     X position of the sound in the world
+/// spatialized.
-/// \param y :     Y position of the sound in the world
+/// The default position of a music is (0, 0, 0).
-/// \param z :     Z position of the sound in the world
+///
+/// \param music Music object
+/// \param x     X coordinate of the position of the music in the scene
+/// \param y     Y coordinate of the position of the music in the scene
+/// \param z     Z coordinate of the position of the music in the scene
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetPosition(sfMusic* music, float x, float y, float z);
 
 ////////////////////////////////////////////////////////////
-/// Make the music's position relative to the listener's
+/// \brief Make a musics's position relative to the listener or absolute
-/// position, or absolute.
-/// The default value is false (absolute)
 ///
-/// \param music :    Music to modify
+/// Making a music relative to the listener will ensure that it will always
-/// \param relative : True to set the position relative, false to set it absolute
+/// be played the same way regardless the position of the listener.
+/// This can be useful for non-spatialized musics, musics that are
+/// produced by the listener, or musics attached to it.
+/// The default value is false (position is absolute).
+///
+/// \param music    Music object
+/// \param relative sfTrue to set the position relative, sfFalse to set it absolute
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative);
 
 ////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
+/// \brief Set the minimum distance of a music
-/// the listener will hear the music at its maximum volume.
-/// The default minimum distance is 1.0
 ///
-/// \param music :    Music to modify
+/// The "minimum distance" of a music is the maximum
-/// \param distance : New minimum distance for the music
+/// distance at which it is heard at its maximum volume. Further
+/// than the minimum distance, it will start to fade out according
+/// to its attenuation factor. A value of 0 ("inside the head
+/// of the listener") is an invalid value and is forbidden.
+/// The default value of the minimum distance is 1.
+///
+/// \param music    Music object
+/// \param distance New minimum distance of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetMinDistance(sfMusic* music, float distance);
 
 ////////////////////////////////////////////////////////////
-/// Set the attenuation factor - the higher the attenuation, the
+/// \brief Set the attenuation factor of a music
-/// more the sound will be attenuated with distance from listener.
-/// The default attenuation factor 1.0
 ///
-/// \param music :       Music to modify
+/// The attenuation is a multiplicative factor which makes
-/// \param attenuation : New attenuation factor for the sound
+/// the music more or less loud according to its distance
+/// from the listener. An attenuation of 0 will produce a
+/// non-attenuated music, i.e. its volume will always be the same
+/// whether it is heard from near or from far. On the other hand,
+/// an attenuation value such as 100 will make the music fade out
+/// very quickly as it gets further from the listener.
+/// The default value of the attenuation is 1.
+///
+/// \param music       Music object
+/// \param attenuation New attenuation factor of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetAttenuation(sfMusic* music, float attenuation);
 
 ////////////////////////////////////////////////////////////
-/// Set the current playing position of a music
+/// \brief Change the current playing position of a music
 ///
-/// \param music :      Music to modify
+/// The playing position can be changed when the music is
-/// \param timeOffset : New playing position, in milliseconds
+/// either paused or playing.
+///
+/// \param music      Music object
+/// \param timeOffset New playing position, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset);
 
 ////////////////////////////////////////////////////////////
-/// Get the pitch of a music
+/// \brief Get the pitch of a music
 ///
-/// \param music : Music to get the pitch from
+/// \param music Music object
 ///
-/// \return Pitch value
+/// \return Pitch of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfMusic_GetPitch(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the volume of a music
+/// \brief Get the volume of a music
 ///
-/// \param music : Music to get the volume from
+/// \param music Music object
 ///
-/// \return Volume value (in range [1, 100])
+/// \return Volume of the music, in the range [0, 100]
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfMusic_GetVolume(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the position of a music
+/// \brief Get the 3D position of a music in the audio scene
 ///
-/// \param music : Music to get the position from
+/// \param music Music object
-/// \param x :     X position of the sound in the world
+/// \param x     X position of the music in the world
-/// \param y :     Y position of the sound in the world
+/// \param y     Y position of the music in the world
-/// \param z :     Z position of the sound in the world
+/// \param z     Z position of the music in the world
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z);
 
 ////////////////////////////////////////////////////////////
-/// Tell if the music's position is relative to the listener's
+/// \brief Tell whether a music's position is relative to the
-/// position, or if it's absolute
+///        listener or is absolute
 ///
-/// \param music : Music to check
+/// \param music Music object
 ///
 /// \return sfTrue if the position is relative, sfFalse if it's absolute
 ///
@@ -281,21 +354,21 @@ CSFML_API void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, flo
 CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the minimum distance of a music
+/// \brief Get the minimum distance of a music
 ///
-/// \param music : Music to get the minimum distance from
+/// \param music Music object
 ///
-/// \return Minimum distance for the music
+/// \return Minimum distance of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfMusic_GetMinDistance(const sfMusic* music);
 
 ////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a music
+/// \brief Get the attenuation factor of a music
 ///
-/// \param music : Music to get the attenuation factor from
+/// \param music Music object
 ///
-/// \return Attenuation factor for the a music
+/// \return Attenuation factor of the music
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfMusic_GetAttenuation(const sfMusic* music);

include/SFML/Audio/Sound.h

@@ -34,87 +34,109 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new sound
+/// \brief Create a new sound
 ///
-/// \return A new sfSound object (NULL if failed)
+/// \return A new sfSound object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSound* sfSound_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Copy an existing sound
+/// \brief Create a new sound by copying an existing one
 ///
-/// \param sound : Sound to copy
+/// \param sound Sound to copy
 ///
-/// \return Copied object
+/// \return A new sfSound object which is a copy of \a sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSound* sfSound_Copy(sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing sound
+/// \brief Destroy a sound
 ///
-/// \param sound : Sound to delete
+/// \param sound Sound to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_Destroy(sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Start playing a sound
+/// \brief Start or resume playing a sound
 ///
-/// \param sound : Sound to play
+/// This function starts the sound if it was stopped, resumes
+/// it if it was paused, and restarts it from beginning if it
+/// was it already playing.
+/// This function uses its own thread so that it doesn't block
+/// the rest of the program while the sound is played.
+///
+/// \param sound Sound object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_Play(sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Pause a sound
+/// \brief Pause a sound
 ///
-/// \param sound : Sound to pause
+/// This function pauses the sound if it was playing,
+/// otherwise (sound already paused or stopped) it has no effect.
+///
+/// \param sound Sound object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_Pause(sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Stop playing a sound
+/// \brief Stop playing a sound
 ///
-/// \param sound : Sound to stop
+/// This function stops the sound if it was playing or paused,
+/// and does nothing if it was already stopped.
+/// It also resets the playing position (unlike sfSound_Pause).
+///
+/// \param sound Sound object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_Stop(sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Bind a sound buffer to a sound
+/// \brief Set the source buffer containing the audio data to play
 ///
-/// \param sound :  Sound to set the loop state
+/// It is important to note that the sound buffer is not copied,
-/// \param buffer : Buffer to bind
+/// thus the sfSoundBuffer object must remain alive as long
+/// as it is attached to the sound.
+///
+/// \param sound  Sound object
+/// \param buffer Sound buffer to attach to the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer);
 
 ////////////////////////////////////////////////////////////
-/// Get the sound buffer bound to a sound
+/// \brief Get the audio buffer attached to a sound
 ///
-/// \param sound : Sound to get the buffer from
+/// \param sound Sound object
 ///
-/// \return Pointer to the sound's buffer
+/// \return Sound buffer attached to the sound (can be NULL)
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Set a sound loop state
+/// \brief Set whether or not a sound should loop after reaching the end
 ///
-/// \param sound : Sound to set the loop state
+/// If set, the sound will restart from beginning after
-/// \param loop :  sfTrue to play in loop, sfFalse to play once
+/// reaching the end and so on, until it is stopped or
+/// sfSound_SetLoop(sound, sfFalse) is called.
+/// The default looping state for sounds is false.
+///
+/// \param sound Sound object
+/// \param loop  sfTrue to play in loop, sfFalse to play once
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetLoop(sfSound* sound, sfBool loop);
 
 ////////////////////////////////////////////////////////////
-/// Tell whether or not a sound is looping
+/// \brief Tell whether or not a soud is in loop mode
 ///
-/// \param sound : Sound to get the loop state from
+/// \param sound Sound object
 ///
 /// \return sfTrue if the sound is looping, sfFalse otherwise
 ///
@@ -122,122 +144,154 @@ CSFML_API void sfSound_SetLoop(sfSound* sound, sfBool loop);
 CSFML_API sfBool sfSound_GetLoop(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the status of a sound (stopped, paused, playing)
+/// \brief Get the current status of a sound (stopped, paused, playing)
 ///
-/// \param sound : Sound to get the status from
+/// \param sound Sound object
 ///
-/// \return Current status of the sound
+/// \return Current status
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSoundStatus sfSound_GetStatus(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Set the pitch of a sound
+/// \brief Set the pitch of a sound
 ///
-/// \param sound : Sound to modify
+/// The pitch represents the perceived fundamental frequency
-/// \param pitch : New pitch
+/// of a sound; thus you can make a sound more acute or grave
+/// by changing its pitch. A side effect of changing the pitch
+/// is to modify the playing speed of the sound as well.
+/// The default value for the pitch is 1.
+///
+/// \param sound Sound object
+/// \param pitch New pitch to apply to the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetPitch(sfSound* sound, float pitch);
 
 ////////////////////////////////////////////////////////////
-/// Set the volume of a sound
+/// \brief Set the volume of a sound
 ///
-/// \param sound :  Sound to modify
+/// The volume is a value between 0 (mute) and 100 (full volume).
-/// \param volume : Volume (in range [0, 100])
+/// The default value for the volume is 100.
+///
+/// \param sound  Sound object
+/// \param volume Volume of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetVolume(sfSound* sound, float volume);
 
 ////////////////////////////////////////////////////////////
-/// Set the position of a sound
+/// \brief Set the 3D position of a sound in the audio scene
 ///
-/// \param sound : Sound to modify
+/// Only sounds with one channel (mono sounds) can be
-/// \param x :     X position of the sound in the world
+/// spatialized.
-/// \param y :     Y position of the sound in the world
+/// The default position of a sound is (0, 0, 0).
-/// \param z :     Z position of the sound in the world
+///
+/// \param sound Sound object
+/// \param x     X coordinate of the position of the sound in the scene
+/// \param y     Y coordinate of the position of the sound in the scene
+/// \param z     Z coordinate of the position of the sound in the scene
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetPosition(sfSound* sound, float x, float y, float z);
 
 ////////////////////////////////////////////////////////////
-/// Make the sound's position relative to the listener's
+/// \brief Make the sound's position relative to the listener or absolute
-/// position, or absolute.
-/// The default value is false (absolute)
 ///
-/// \param sound :    Sound to modify
+/// Making a sound relative to the listener will ensure that it will always
-/// \param relative : True to set the position relative, false to set it absolute
+/// be played the same way regardless the position of the listener.
+/// This can be useful for non-spatialized sounds, sounds that are
+/// produced by the listener, or sounds attached to it.
+/// The default value is false (position is absolute).
+///
+/// \param sound    Sound object
+/// \param relative sfTrue to set the position relative, sfFalse to set it absolute
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetRelativeToListener(sfSound* sound, sfBool relative);
 
 ////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
+/// \brief Set the minimum distance of a sound
-/// the listener will hear the sound at its maximum volume.
-/// The default minimum distance is 1.0
 ///
-/// \param sound :    Sound to modify
+/// The "minimum distance" of a sound is the maximum
-/// \param distance : New minimum distance for the sound
+/// distance at which it is heard at its maximum volume. Further
+/// than the minimum distance, it will start to fade out according
+/// to its attenuation factor. A value of 0 ("inside the head
+/// of the listener") is an invalid value and is forbidden.
+/// The default value of the minimum distance is 1.
+///
+/// \param sound    Sound object
+/// \param distance New minimum distance of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetMinDistance(sfSound* sound, float distance);
 
 ////////////////////////////////////////////////////////////
-/// Set the attenuation factor - the higher the attenuation, the
+/// \brief Set the attenuation factor of a sound
-/// more the sound will be attenuated with distance from listener.
-/// The default attenuation factor is 1.0
 ///
-/// \param sound :       Sound to modify
+/// The attenuation is a multiplicative factor which makes
-/// \param attenuation : New attenuation factor for the sound
+/// the sound more or less loud according to its distance
+/// from the listener. An attenuation of 0 will produce a
+/// non-attenuated sound, i.e. its volume will always be the same
+/// whether it is heard from near or from far. On the other hand,
+/// an attenuation value such as 100 will make the sound fade out
+/// very quickly as it gets further from the listener.
+/// The default value of the attenuation is 1.
+///
+/// \param sound       Sound object
+/// \param attenuation New attenuation factor of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetAttenuation(sfSound* sound, float attenuation);
 
 ////////////////////////////////////////////////////////////
-/// Set the current playing position of a sound
+/// \brief Change the current playing position of a sound
 ///
-/// \param sound :      Sound to modify
+/// The playing position can be changed when the sound is
-/// \param timeOffset : New playing position, in milliseconds
+/// either paused or playing.
+///
+/// \param sound      Sound object
+/// \param timeOffset New playing position, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset);
 
 ////////////////////////////////////////////////////////////
-/// Get the pitch of a sound
+/// \brief Get the pitch of a sound
 ///
-/// \param sound : Sound to get the pitch from
+/// \param sound Sound object
 ///
-/// \return Pitch value
+/// \return Pitch of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSound_GetPitch(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the volume of a sound
+/// \brief Get the volume of a sound
 ///
-/// \param sound : Sound to get the volume from
+/// \param sound Sound object
 ///
-/// \return Volume value (in range [1, 100])
+/// \return Volume of the sound, in the range [0, 100]
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSound_GetVolume(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the position of a sound
+/// \brief Get the 3D position of a sound in the audio scene
 ///
-/// \param sound : Sound to get the position from
+/// \param sound Sound object
-/// \param x :     X position of the sound in the world
+/// \param x     X position of the sound in the world
-/// \param y :     Y position of the sound in the world
+/// \param y     Y position of the sound in the world
-/// \param z :     Z position of the sound in the world
+/// \param z     Z position of the sound in the world
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z);
 
 ////////////////////////////////////////////////////////////
-/// Tell if the sound's position is relative to the listener's
+/// \brief Tell whether a sound's position is relative to the
-/// position, or if it's absolute
+///        listener or is absolute
 ///
-/// \param sound : Sound to check
+/// \param sound Sound object
 ///
 /// \return sfTrue if the position is relative, sfFalse if it's absolute
 ///
@@ -245,29 +299,29 @@ CSFML_API void sfSound_GetPosition(const sfSound* sound, float* x, float* y, flo
 CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the minimum distance of a sound
+/// \brief Get the minimum distance of a sound
 ///
-/// \param sound : Sound to get the minimum distance from
+/// \param sound Sound object
 ///
-/// \return Minimum distance for the sound
+/// \return Minimum distance of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSound_GetMinDistance(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a sound
+/// \brief Get the attenuation factor of a sound
 ///
-/// \param sound : Sound to get the attenuation factor from
+/// \param sound Sound object
 ///
-/// \return Attenuation factor for the sound
+/// \return Attenuation factor of the sound
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSound_GetAttenuation(const sfSound* sound);
 
 ////////////////////////////////////////////////////////////
-/// Get the current playing position of a sound
+/// \brief Get the current playing position of a sound
 ///
-/// \param sound : Sound to get the position from
+/// \param sound Sound object
 ///
 /// \return Current playing position, in milliseconds
 ///

include/SFML/Audio/SoundBuffer.h

@@ -30,13 +30,18 @@
 ////////////////////////////////////////////////////////////
 #include <SFML/Config.h>
 #include <SFML/Audio/Types.h>
+#include <SFML/System/InputStream.h>
 #include <stddef.h>
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from a file
+/// \brief Create a new sound buffer and load it from a file
 ///
-/// \param filename : Path of the music file to open
+/// 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.
+///
+/// \param filename Path of the sound file to load
 ///
 /// \return A new sfSoundBuffer object (NULL if failed)
 ///
@@ -44,10 +49,14 @@
 CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename);
 
 ////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from a file in memory
+/// \brief Create a new sound buffer and load it 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.
+///
+/// \param data        Pointer to the file data in memory
+/// \param sizeInBytes Size of the data to load, in bytes
 ///
 /// \return A new sfSoundBuffer object (NULL if failed)
 ///
@@ -55,14 +64,29 @@ CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename);
 CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInBytes);
 
 ////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from an array of
+/// \brief Create a new sound buffer and load it from a custom stream
-/// samples in memory - assumed format for samples is
-/// 16 bits signed integer
 ///
-/// \param samples :       Pointer to the samples in memory
+/// Here is a complete list of all the supported audio formats:
-/// \param samplesCount :  Number of samples pointed by Samples
+/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
-/// \param channelsCount : Number of channels (1 = mono, 2 = stereo, ...)
+/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
-/// \param sampleRate :    Frequency (number of samples to play per second)
+///
+/// \param stream Source stream to read from
+///
+/// \return A new sfSoundBuffer object (NULL if failed)
+///
+////////////////////////////////////////////////////////////
+CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromStream(sfInputStream* stream);
+
+////////////////////////////////////////////////////////////
+/// \brief Create a new sound buffer and load it from an array of samples in memory
+///
+/// The assumed format of the audio samples is 16 bits signed integer
+/// (sfInt16).
+///
+/// \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 A new sfSoundBuffer object (NULL if failed)
 ///
@@ -70,48 +94,59 @@ CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t
 CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate);
 
 ////////////////////////////////////////////////////////////
-/// Copy an existing sound buffer
+/// \brief Create a new sound buffer by copying an existing one
 ///
-/// \param soundBuffer : Sound buffer to copy
+/// \param soundBuffer Sound buffer to copy
 ///
-/// \return Copied object
+/// \return A new sfSoundBuffer object which is a copy of \a soundBuffer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing sound buffer
+/// \brief Destroy a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to delete
+/// \param soundBuffer Sound buffer to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Save a sound buffer to a file
+/// \brief Save a sound buffer to an audio file
 ///
-/// \param soundBuffer : Sound buffer to save
+/// Here is a complete list of all the supported audio formats:
-/// \param filename :    Path of the sound file to write
+/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
+/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
 ///
-/// \return sfTrue if saving has been successful
+/// \param soundBuffer Sound buffer object
+/// \param filename    Path of the sound file to write
+///
+/// \return sfTrue if saving succeeded, sfFalse if it failed
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* filename);
 
 ////////////////////////////////////////////////////////////
-/// Return the samples contained in a sound buffer
+/// \brief Get the array of audio samples stored in a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to get samples from
+/// The format of the returned samples is 16 bits signed integer
+/// (sfInt16). The total number of samples in this array
+/// is given by the sfSoundBuffer_GetSamplesCount function.
 ///
-/// \return Pointer to the array of sound samples, in 16 bits signed integer format
+/// \param soundBuffer Sound buffer object
+///
+/// \return Read-only pointer to the array of sound samples
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Return the number of samples contained in a sound buffer
+/// \brief Get the number of samples stored in a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to get samples count from
+/// The array of samples can be accessed with the
+/// sfSoundBuffer_GetSamples function.
+///
+/// \param soundBuffer Sound buffer object
 ///
 /// \return Number of samples
 ///
@@ -119,19 +154,26 @@ CSFML_API const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuff
 CSFML_API size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound buffer
+/// \brief Get the sample rate of a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to get sample rate from
+/// 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 Sound frequency (number of samples per second)
+/// \param soundBuffer Sound buffer object
+///
+/// \return Sample rate (number of samples per second)
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Return the number of channels of a sound buffer (1 = mono, 2 = stereo, ...)
+/// \brief Get the number of channels used by a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to get channels count from
+/// If the sound is mono then the number of channels will
+/// be 1, 2 for stereo, etc.
+///
+/// \param soundBuffer Sound buffer object
 ///
 /// \return Number of channels
 ///
@@ -139,9 +181,9 @@ CSFML_API unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuf
 CSFML_API unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer);
 
 ////////////////////////////////////////////////////////////
-/// Get the duration of a sound buffer
+/// \brief Get the total duration of a sound buffer
 ///
-/// \param soundBuffer : Sound buffer to get duration from
+/// \param soundBuffer Sound buffer object
 ///
 /// \return Sound duration, in milliseconds
 ///

include/SFML/Audio/SoundBufferRecorder.h

@@ -33,7 +33,7 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new sound buffer recorder
+/// \brief Create a new sound buffer recorder
 ///
 /// \return A new sfSoundBufferRecorder object (NULL if failed)
 ///
@@ -41,48 +41,62 @@
 CSFML_API sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing sound buffer recorder
+/// \brief Destroy a sound buffer recorder
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to delete
+/// \param soundBufferRecorder Sound buffer recorder to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Start the capture.
+/// \brief Start the capture of a sound recorder recorder
-/// Warning : only one capture can happen at the same time
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to start
+/// The \a sampleRate parameter defines the number of audio samples
-/// \param sampleRate :          Sound frequency (the more samples, the higher the quality)
+/// captured per second. The higher, the better the quality
+/// (for example, 44100 samples/sec is CD quality).
+/// This function uses its own thread so that it doesn't block
+/// the rest of the program while the capture runs.
+/// Please note that only one capture can happen at the same time.
+///
+/// \param soundBufferRecorder Sound buffer recorder object
+/// \param sampleRate          Desired capture rate, in number of samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, unsigned int sampleRate);
 
 ////////////////////////////////////////////////////////////
-/// Stop the capture
+/// \brief Stop the capture of a sound recorder
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to stop
+/// \param soundBufferRecorder Sound buffer recorder object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound buffer recorder
+/// \brief Get the sample rate of a sound buffer recorder
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to get sample rate from
+/// The sample rate defines the number of audio samples
+/// captured per second. The higher, the better the quality
+/// (for example, 44100 samples/sec is CD quality).
 ///
-/// \return Frequency, in samples per second
+/// \param soundBufferRecorder Sound buffer recorder object
+///
+/// \return Sample rate, in samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* soundBufferRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Get the sound buffer containing the captured audio data
+/// \brief Get the sound buffer containing the captured audio data
-/// of a sound buffer recorder
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to get the sound buffer from
+/// The sound buffer is valid only after the capture has ended.
+/// This function provides a read-only access to the internal
+/// sound buffer, but it can be copied if you need to
+/// make any modification to it.
 ///
-/// \return Pointer to the sound buffer (you don't need to destroy it after use)
+/// \param soundBufferRecorder Sound buffer recorder object
+///
+/// \return Read-only access to the sound buffer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const sfSoundBuffer* sfSoundBufferRecorder_GetBuffer(const sfSoundBufferRecorder* soundBufferRecorder);

include/SFML/Audio/SoundRecorder.h

@@ -39,13 +39,12 @@ typedef void   (*sfSoundRecorderStopCallback)(void*);
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new sound recorder with callback functions
+/// \brief Construct a new sound recorder from callback functions
-/// for processing captured samples
 ///
-/// \param onStart :   Callback function which will be called when a new capture starts (can be NULL)
+/// \param onStart   Callback function which will be called when a new capture starts (can be NULL)
-/// \param onProcess : Callback function which will be called each time there's audio data to process
+/// \param onProcess Callback function which will be called each time there's audio data to process
-/// \param onStop :    Callback function which will be called when the current capture stops (can be NULL)
+/// \param onStop    Callback function which will be called when the current capture stops (can be NULL)
-/// \param userData :  Data to pass to the callback function (can be NULL)
+/// \param userData  Data to pass to the callback function (can be NULL)
 ///
 /// \return A new sfSoundRecorder object (NULL if failed)
 ///
@@ -56,46 +55,59 @@ CSFML_API sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback
                                                   void*                          userData);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing sound recorder
+/// \brief Destroy a sound recorder
 ///
-/// \param soundRecorder : Sound recorder to delete
+/// \param soundRecorder Sound recorder to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Start the capture.
+/// \brief Start the capture of a sound recorder
-/// Warning : only one capture can happen at the same time
 ///
-/// \param soundRecorder : Sound recorder to start
+/// The \a sampleRate parameter defines the number of audio samples
-/// \param sampleRate :    Sound frequency (the more samples, the higher the quality)
+/// captured per second. The higher, the better the quality
+/// (for example, 44100 samples/sec is CD quality).
+/// This function uses its own thread so that it doesn't block
+/// the rest of the program while the capture runs.
+/// Please note that only one capture can happen at the same time.
+///
+/// \param soundRecorder Sound recorder object
+/// \param sampleRate    Desired capture rate, in number of samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRate);
 
 ////////////////////////////////////////////////////////////
-/// Stop the capture
+/// \brief Stop the capture of a sound recorder
 ///
-/// \param soundRecorder : Sound recorder to stop
+/// \param soundRecorder Sound recorder object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound recorder
+/// \brief Get the sample rate of a sound recorder
 ///
-/// \param soundRecorder : Sound recorder to get sample rate from
+/// The sample rate defines the number of audio samples
+/// captured per second. The higher, the better the quality
+/// (for example, 44100 samples/sec is CD quality).
 ///
-/// \return Frequency, in samples per second
+/// \param soundRecorder Sound recorder object
+///
+/// \return Sample rate, in samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder);
 
 ////////////////////////////////////////////////////////////
-/// Tell if the system supports sound capture.
+/// \brief Check if the system supports audio capture
-/// If not, this class won't be usable
 ///
-/// \return sfTrue if audio capture is supported
+/// This function should always be called before using
+/// the audio capture features. If it returns false, then
+/// any attempt to use sfSoundRecorder will fail.
+///
+/// \return sfTrue if audio capture is supported, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSoundRecorder_IsAvailable(void);

include/SFML/Audio/SoundStatus.h

@@ -31,6 +31,10 @@
 #include <SFML/Config.h>
 
 
+////////////////////////////////////////////////////////////
+/// \brief Enumeration of statuses for sounds and musics
+///
+////////////////////////////////////////////////////////////
 typedef enum
 {
     sfStopped, ///< Sound / music is not playing

include/SFML/Audio/SoundStream.h

@@ -34,8 +34,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// sfSoundStreamChunk defines the data to fill by the
+/// \brief defines the data to fill by the OnGetData callback
-/// OnGetData callback
+///
 ////////////////////////////////////////////////////////////
 typedef struct
 {
@@ -48,15 +48,15 @@ typedef void   (*sfSoundStreamSeekCallback)(sfUint32, void*);               ///<
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new sound stream
+/// \brief Create a new sound stream
 ///
-/// \param onGetData :     Function called when the stream needs more data (can't be NULL)
+/// \param onGetData     Function called when the stream needs more data (can't be NULL)
-/// \param onSeek :        Function called when the stream seeks (can't be NULL)
+/// \param onSeek        Function called when the stream seeks (can't be NULL)
-/// \param channelsCount : Number of channels to use (1 = mono, 2 = stereo)
+/// \param channelsCount Number of channels to use (1 = mono, 2 = stereo)
-/// \param sampleRate :    Sample rate of the sound (44100 = CD quality)
+/// \param sampleRate    Sample rate of the sound (44100 = CD quality)
-/// \param userData :      Data to pass to the callback functions
+/// \param userData      Data to pass to the callback functions
 ///
-/// \return A new sfSoundStream object (NULL if failed)
+/// \return A new sfSoundStream object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData,
@@ -66,52 +66,66 @@ CSFML_API sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGet
                                               void*                        userData);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing sound stream
+/// \brief Destroy a sound stream
 ///
-/// \param soundStream : Sound stream to delete
+/// \param soundStream Sound stream to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_Destroy(sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Start playing a sound stream
+/// \brief Start or resume playing a sound stream
 ///
-/// \param soundStream : Sound stream to play
+/// This function starts the stream if it was stopped, resumes
+/// it if it was paused, and restarts it from beginning if it
+/// was it already playing.
+/// This function uses its own thread so that it doesn't block
+/// the rest of the program while the music is played.
+///
+/// \param soundStream Sound stream object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_Play(sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Pause a sound stream
+/// \brief Pause a sound stream
 ///
-/// \param soundStream : Sound stream to pause
+/// This function pauses the stream if it was playing,
+/// otherwise (stream already paused or stopped) it has no effect.
+///
+/// \param soundStream Sound stream object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_Pause(sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Stop playing a sound stream
+/// \brief Stop playing a sound stream
 ///
-/// \param soundStream : Sound stream to stop
+/// This function stops the stream if it was playing or paused,
+/// and does nothing if it was already stopped.
+/// It also resets the playing position (unlike sfSoundStream_Pause).
+///
+/// \param soundStream Sound stream object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_Stop(sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the status of a sound stream (stopped, paused, playing)
+/// \brief Get the current status of a sound stream (stopped, paused, playing)
 ///
-/// \param soundStream : Sound stream to get the status from
+/// \param soundStream Sound stream object
 ///
-/// \return Current status of the sound stream
+/// \return Current status
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Return the number of channels of a sound stream
+/// \brief Return the number of channels of a sound stream
-/// (1 = mono, 2 = stereo)
 ///
-/// \param soundStream : Sound stream to get the channels count from
+/// 1 channel means a mono sound, 2 means stereo, etc.
+///
+/// \param soundStream Sound stream object
 ///
 /// \return Number of channels
 ///
@@ -119,131 +133,171 @@ CSFML_API sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream
 CSFML_API unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound stream
+/// \brief Get the sample rate of a sound stream
 ///
-/// \param soundStream : Sound stream to get the sample rate from
+/// The sample rate is the number of audio samples played per
+/// second. The higher, the better the quality.
 ///
-/// \return Stream frequency (number of samples per second)
+/// \param soundStream Sound stream object
+///
+/// \return Sample rate, in number of samples per second
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Set the pitch of a sound stream
+/// \brief Set the pitch of a sound stream
 ///
-/// \param soundStream : Sound stream to modify
+/// The pitch represents the perceived fundamental frequency
-/// \param pitch :       New pitch
+/// of a sound; thus you can make a stream more acute or grave
+/// by changing its pitch. A side effect of changing the pitch
+/// is to modify the playing speed of the stream as well.
+/// The default value for the pitch is 1.
+///
+/// \param soundStream Sound stream object
+/// \param pitch       New pitch to apply to the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch);
 
 ////////////////////////////////////////////////////////////
-/// Set the volume of a sound stream
+/// \brief Set the volume of a sound stream
 ///
-/// \param soundStream : Sound stream to modify
+/// The volume is a value between 0 (mute) and 100 (full volume).
-/// \param volume :      Volume (in range [0, 100])
+/// The default value for the volume is 100.
+///
+/// \param soundStream Sound stream object
+/// \param volume      Volume of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume);
 
 ////////////////////////////////////////////////////////////
-/// Set the position of a sound stream
+/// \brief Set the 3D position of a sound stream in the audio scene
 ///
-/// \param soundStream : Sound stream to modify
+/// Only streams with one channel (mono streams) can be
-/// \param x :           X position of the sound stream in the world
+/// spatialized.
-/// \param y :           Y position of the sound stream in the world
+/// The default position of a stream is (0, 0, 0).
-/// \param z :           Z position of the sound stream in the world
+///
+/// \param soundStream Sound stream object
+/// \param x           X coordinate of the position of the stream in the scene
+/// \param y           Y coordinate of the position of the stream in the scene
+/// \param z           Z coordinate of the position of the stream in the scene
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, float z);
 
 ////////////////////////////////////////////////////////////
-/// Make the sound stream's position relative to the listener's
+/// \brief Make a sound stream's position relative to the listener or absolute
-/// position, or absolute.
-/// The default value is false (absolute)
 ///
-/// \param soundStream : Sound stream to modify
+/// Making a stream relative to the listener will ensure that it will always
-/// \param relative :    True to set the position relative, false to set it absolute
+/// be played the same way regardless the position of the listener.
+/// This can be useful for non-spatialized streams, streams that are
+/// produced by the listener, or streams attached to it.
+/// The default value is false (position is absolute).
+///
+/// \param soundStream Sound stream object
+/// \param relative    sfTrue to set the position relative, sfFalse to set it absolute
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool relative);
 
 ////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
+/// \brief Set the minimum distance of a sound stream
-/// the listener will hear the sound stream at its maximum volume.
-/// The default minimum distance is 1.0
 ///
-/// \param soundStream : Sound stream to modify
+/// The "minimum distance" of a stream is the maximum
-/// \param distance :    New minimum distance for the sound stream
+/// distance at which it is heard at its maximum volume. Further
+/// than the minimum distance, it will start to fade out according
+/// to its attenuation factor. A value of 0 ("inside the head
+/// of the listener") is an invalid value and is forbidden.
+/// The default value of the minimum distance is 1.
+///
+/// \param soundStream Sound stream object
+/// \param distance    New minimum distance of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance);
 
 ////////////////////////////////////////////////////////////
-/// Set the attenuation factor - the higher the attenuation, the
+/// \brief Set the attenuation factor of a sound stream
-/// more the sound stream will be attenuated with distance from listener.
-/// The default attenuation factor 1.0
 ///
-/// \param soundStream : Sound stream to modify
+/// The attenuation is a multiplicative factor which makes
-/// \param attenuation : New attenuation factor for the sound stream
+/// the stream more or less loud according to its distance
+/// from the listener. An attenuation of 0 will produce a
+/// non-attenuated stream, i.e. its volume will always be the same
+/// whether it is heard from near or from far. On the other hand,
+/// an attenuation value such as 100 will make the stream fade out
+/// very quickly as it gets further from the listener.
+/// The default value of the attenuation is 1.
+///
+/// \param soundStream Sound stream object
+/// \param attenuation New attenuation factor of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation);
 
 ////////////////////////////////////////////////////////////
-/// Set the current playing position of a stream
+/// \brief Change the current playing position of a sound stream
 ///
-/// \param soundStream : Sound stream to modify
+/// The playing position can be changed when the stream is
-/// \param timeOffset :  New playing position, in milliseconds
+/// either paused or playing.
+///
+/// \param soundStream Sound stream object
+/// \param timeOffset  New playing position, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOffset);
 
 ////////////////////////////////////////////////////////////
-/// Set a stream loop state
+/// \brief Set whether or not a sound stream should loop after reaching the end
 ///
-/// \param soundStream : Stream to set the loop state
+/// If set, the stream will restart from beginning after
-/// \param loop :        sfTrue to play in loop, sfFalse to play once
+/// reaching the end and so on, until it is stopped or
+/// sfSoundStream_SetLoop(stream, sfFalse) is called.
+/// The default looping state for sound streams is false.
+///
+/// \param soundStream Sound stream object
+/// \param loop        sfTrue to play in loop, sfFalse to play once
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop);
 
 ////////////////////////////////////////////////////////////
-/// Get the pitch of a sound stream
+/// \brief Get the pitch of a sound stream
 ///
-/// \param soundStream : Sound stream to get the pitch from
+/// \param soundStream Sound stream object
 ///
-/// \return Pitch value
+/// \return Pitch of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSoundStream_GetPitch(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the volume of a sound stream
+/// \brief Get the volume of a sound stream
 ///
-/// \param soundStream : Sound stream to get the volume from
+/// \param soundStream Sound stream object
 ///
-/// \return Volume value (in range [1, 100])
+/// \return Volume of the stream, in the range [0, 100]
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSoundStream_GetVolume(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the position of a sound stream
+/// \brief Get the 3D position of a sound stream in the audio scene
 ///
-/// \param soundStream : Sound stream to get the position from
+/// \param soundStream Sound stream object
-/// \param x :           X position of the sound stream in the world
+/// \param x           X position of the stream in the world
-/// \param y :           Y position of the sound stream in the world
+/// \param y           Y position of the stream in the world
-/// \param z :           Z position of the sound stream in the world
+/// \param z           Z position of the stream in the world
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float* y, float* z);
 
 ////////////////////////////////////////////////////////////
-/// Tell if the sound stream's position is relative to the listener's
+/// \brief Tell whether a sound stream's position is relative to the
-/// position, or if it's absolute
+///        listener or is absolute
 ///
-/// \param soundStream : Sound stream to check
+/// \param soundStream Sound stream object
 ///
 /// \return sfTrue if the position is relative, sfFalse if it's absolute
 ///
@@ -251,39 +305,39 @@ CSFML_API void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float
 CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the minimum distance of a sound stream
+/// \brief Get the minimum distance of a sound stream
 ///
-/// \param soundStream : Sound stream to get the minimum distance from
+/// \param soundStream Sound stream object
 ///
-/// \return Minimum distance for the sound stream
+/// \return Minimum distance of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a sound stream
+/// \brief Get the attenuation factor of a sound stream
 ///
-/// \param soundStream : Sound stream to get the attenuation factor from
+/// \param soundStream Sound stream object
 ///
-/// \return Attenuation factor for the sound stream
+/// \return Attenuation factor of the stream
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Tell whether or not a stream is looping
+/// \brief Tell whether or not a sound stream is in loop mode
 ///
-/// \param soundStream : Soundstream to get the loop state from
+/// \param soundStream Sound stream object
 ///
-/// \return sfTrue if the stream is looping, sfFalse otherwise
+/// \return sfTrue if the music is looping, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream);
 
 ////////////////////////////////////////////////////////////
-/// Get the current playing position of a sound stream
+/// \brief Get the current playing position of a sound stream
 ///
-/// \param soundStream : Sound stream to get the position from
+/// \param soundStream Sound stream object
 ///
 /// \return Current playing position, in milliseconds
 ///

include/SFML/Network/Ftp.h

@@ -35,7 +35,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Enumerate all the FTP file transfer modes
+/// \brief Enumeration of transfer modes
+///
 ////////////////////////////////////////////////////////////
 enum sfFtpTransferMode
 {
@@ -46,8 +47,8 @@ enum sfFtpTransferMode
 
 
 ////////////////////////////////////////////////////////////
-/// Enumerate all the valid status codes returned in
+/// \brief Status codes possibly returned by a FTP response
-/// a FTP response
+///
 ////////////////////////////////////////////////////////////
 enum sfFtpStatus
 {
@@ -113,28 +114,30 @@ enum sfFtpStatus
 
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp listing response
+/// \brief Destroy a FTP listing response
 ///
-/// \param ftpListingResponse : Ftp listing response to destroy
+/// \param ftpListingResponse Ftp listing response to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse);
 
 ////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
+/// \brief Check if a FTP listing response status code means a success
-/// means a success
 ///
-/// \param ftpListingResponse : Ftp listing response
+/// This function is defined for convenience, it is
+/// equivalent to testing if the status code is < 400.
 ///
-/// \return sfTrue if status is success (code < 400)
+/// \param ftpListingResponse Ftp listing response
+///
+/// \return sfTrue if the status is a success, sfFalse if it is a failure
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the response status code
+/// \brief Get the status code of a FTP listing response
 ///
-/// \param ftpListingResponse : Ftp listing response
+/// \param ftpListingResponse Ftp listing response
 ///
 /// \return Status code
 ///
@@ -142,9 +145,9 @@ CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListin
 CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListingResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
+/// \brief Get the full message contained in a FTP listing response
 ///
-/// \param ftpListingResponse : Ftp listing response
+/// \param ftpListingResponse Ftp listing response
 ///
 /// \return The response message
 ///
@@ -152,49 +155,51 @@ CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse*
 CSFML_API const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListingResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the number of filenames in the listing
+/// \brief Return the number of filenames contained in a FTP listing response
 ///
-/// \param ftpListingResponse : Ftp listing response
+/// \param ftpListingResponse Ftp listing response
 ///
-/// \return Total number of filenames
+/// \return Total number of filenames available
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the Index-th filename in the directory
+/// \brief Return a filename contained in a FTP listing response
 ///
-/// \param ftpListingResponse : Ftp listing response
+/// \param ftpListingResponse Ftp listing response
-/// \param index :              Index of the filename to get
+/// \param index              Index of the filename to get (in range [0 .. GetCount])
 ///
-/// \return Index-th filename
+/// \return Array containing the requested filenames
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpListingResponse, size_t index);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp directory response
+/// \brief Destroy a FTP directory response
 ///
-/// \param ftpDirectoryResponse : Ftp directory response to destroy
+/// \param ftpDirectoryResponse Ftp directory response to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse);
 
 ////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
+/// \brief Check if a FTP directory response status code means a success
-/// means a success
 ///
-/// \param ftpDirectoryResponse : Ftp directory response
+/// This function is defined for convenience, it is
+/// equivalent to testing if the status code is < 400.
 ///
-/// \return sfTrue if status is success (code < 400)
+/// \param ftpDirectoryResponse Ftp directory response
+///
+/// \return sfTrue if the status is a success, sfFalse if it is a failure
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the response status code
+/// \brief Get the status code of a FTP directory response
 ///
-/// \param ftpDirectoryResponse : Ftp directory response
+/// \param ftpDirectoryResponse Ftp directory response
 ///
 /// \return Status code
 ///
@@ -202,9 +207,9 @@ CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDi
 CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDirectoryResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
+/// \brief Get the full message contained in a FTP directory response
 ///
-/// \param ftpDirectoryResponse : Ftp directory response
+/// \param ftpDirectoryResponse Ftp directory response
 ///
 /// \return The response message
 ///
@@ -212,9 +217,9 @@ CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryRespo
 CSFML_API const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpDirectoryResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the directory returned in the response
+/// \brief Get the directory returned in a FTP directory response
 ///
-/// \param ftpDirectoryResponse : Ftp directory response
+/// \param ftpDirectoryResponse Ftp directory response
 ///
 /// \return Directory name
 ///
@@ -223,28 +228,30 @@ CSFML_API const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryRe
 
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp response
+/// \brief Destroy a FTP response
 ///
-/// \param ftpResponse : Ftp response to destroy
+/// \param ftpResponse Ftp response to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
+/// \brief Check if a FTP response status code means a success
-/// means a success
 ///
-/// \param ftpResponse : Ftp response
+/// This function is defined for convenience, it is
+/// equivalent to testing if the status code is < 400.
 ///
-/// \return sfTrue if status is success (code < 400)
+/// \param ftpResponse Ftp response object
+///
+/// \return sfTrue if the status is a success, sfFalse if it is a failure
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the response status code
+/// \brief Get the status code of a FTP response
 ///
-/// \param ftpResponse : Ftp response
+/// \param ftpResponse Ftp response object
 ///
 /// \return Status code
 ///
@@ -252,9 +259,9 @@ CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse);
 CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
+/// \brief Get the full message contained in a FTP response
 ///
-/// \param ftpResponse : Ftp response
+/// \param ftpResponse Ftp response object
 ///
 /// \return The response message
 ///
@@ -262,28 +269,37 @@ CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse);
 CSFML_API const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Construct a new Ftp
+/// \brief Create a new Ftp object
 ///
-/// \return Pointer to the new Ftp
+/// \return A new sfFtp object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfFtp* sfFtp_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp
+/// \brief Destroy a Ftp object
 ///
-/// \param ftp : Ftp to destroy
+/// \param ftp Ftp object to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfFtp_Destroy(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Connect to the specified FTP server
+/// \brief Connect to the specified FTP server
 ///
-/// \param ftp :     Ftp instance
+/// The port should be 21, which is the standard
-/// \param server :  FTP server to connect to
+/// port used by the FTP protocol. You shouldn't use a different
-/// \param port :    Port used for connection (21 by default, standard FTP port)
+/// value, unless you really know what you do.
-/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
+/// This function tries to connect to the server so it may take
+/// a while to complete, especially if the server is not
+/// reachable. To avoid blocking your application for too long,
+/// you can use a timeout. Using 0 means that the
+/// system timeout will be used (which is usually pretty long).
+///
+/// \param ftp     Ftp object
+/// \param server  Name or address of the FTP server to connect to
+/// \param port    Port used for the connection
+/// \param timeout Maximum time to wait, in milliseconds
 ///
 /// \return Server response to the request
 ///
@@ -291,9 +307,12 @@ CSFML_API void sfFtp_Destroy(sfFtp* ftp);
 CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port, sfUint32 timeout);
 
 ////////////////////////////////////////////////////////////
-/// Log in using anonymous account
+/// \brief Log in using an anonymous account
 ///
-/// \param ftp : Ftp instance
+/// Logging in is mandatory after connecting to the server.
+/// Users that are not logged in cannot perform any operation.
+///
+/// \param ftp Ftp object
 ///
 /// \return Server response to the request
 ///
@@ -301,11 +320,14 @@ CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned
 CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Log in using a username and a password
+/// \brief Log in using a username and a password
 ///
-/// \param ftp :      Ftp instance
+/// Logging in is mandatory after connecting to the server.
-/// \param userName : User name
+/// Users that are not logged in cannot perform any operation.
-/// \param password : Password
+///
+/// \param ftp      Ftp object
+/// \param name     User name
+/// \param password Password
 ///
 /// \return Server response to the request
 ///
@@ -313,9 +335,9 @@ CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp);
 CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* password);
 
 ////////////////////////////////////////////////////////////
-/// Close the connection with FTP server
+/// \brief Close the connection with the server
 ///
-/// \param ftp : Ftp instance
+/// \param ftp Ftp object
 ///
 /// \return Server response to the request
 ///
@@ -323,9 +345,12 @@ CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const cha
 CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Send a null command just to prevent from being disconnected
+/// \brief Send a null command to keep the connection alive
 ///
-/// \param ftp : Ftp instance
+/// This command is useful because the server may close the
+/// connection automatically if no command is sent.
+///
+/// \param ftp Ftp object
 ///
 /// \return Server response to the request
 ///
@@ -333,9 +358,12 @@ CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp);
 CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Get the current working directory
+/// \brief Get the current working directory
 ///
-/// \param ftp : Ftp instance
+/// The working directory is the root path for subsequent
+/// operations involving directories and/or filenames.
+///
+/// \param ftp Ftp object
 ///
 /// \return Server response to the request
 ///
@@ -343,11 +371,15 @@ CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp);
 CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Get the contents of the given directory
+/// \brief Get the contents of the given directory
-/// (subdirectories and files)
 ///
-/// \param ftp :       Ftp instance
+/// This function retrieves the sub-directories and files
-/// \param directory : Directory to list ("" by default, the current one)
+/// contained in the given directory. It is not recursive.
+/// The \a directory parameter is relative to the current
+/// working directory.
+///
+/// \param ftp       Ftp object
+/// \param directory Directory to list
 ///
 /// \return Server response to the request
 ///
@@ -355,10 +387,12 @@ CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp);
 CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* directory);
 
 ////////////////////////////////////////////////////////////
-/// Change the current working directory
+/// \brief Change the current working directory
 ///
-/// \param ftp :       Ftp instance
+/// The new directory must be relative to the current one.
-/// \param directory : New directory, relative to the current one
+///
+/// \param ftp       Ftp object
+/// \param directory New working directory
 ///
 /// \return Server response to the request
 ///
@@ -366,9 +400,9 @@ CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char
 CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory);
 
 ////////////////////////////////////////////////////////////
-/// Go to the parent directory of the current one
+/// \brief Go to the parent directory of the current one
 ///
-/// \param ftp : Ftp instance
+/// \param ftp Ftp object
 ///
 /// \return Server response to the request
 ///
@@ -376,10 +410,13 @@ CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory
 CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp);
 
 ////////////////////////////////////////////////////////////
-/// Create a new directory
+/// \brief Create a new directory
 ///
-/// \param ftp :  Ftp instance
+/// The new directory is created as a child of the current
-/// \param name : Name of the directory to create
+/// working directory.
+///
+/// \param ftp  Ftp object
+/// \param name Name of the directory to create
 ///
 /// \return Server response to the request
 ///
@@ -387,10 +424,15 @@ CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp);
 CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name);
 
 ////////////////////////////////////////////////////////////
-/// Remove an existing directory
+/// \brief Remove an existing directory
 ///
-/// \param ftp :  Ftp instance
+/// The directory to remove must be relative to the
-/// \param name : Name of the directory to remove
+/// current working directory.
+/// Use this function with caution, the directory will
+/// be removed permanently!
+///
+/// \param ftp  Ftp object
+/// \param name Name of the directory to remove
 ///
 /// \return Server response to the request
 ///
@@ -398,11 +440,14 @@ CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name);
 CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name);
 
 ////////////////////////////////////////////////////////////
-/// Rename a file
+/// \brief Rename an existing file
 ///
-/// \param ftp :     Ftp instance
+/// The filenames must be relative to the current working
-/// \param file :    File to rename
+/// directory.
-/// \param newName : New name
+///
+/// \param ftp     Ftp object
+/// \param file    File to rename
+/// \param newName New name of the file
 ///
 /// \return Server response to the request
 ///
@@ -410,10 +455,15 @@ CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name);
 CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newName);
 
 ////////////////////////////////////////////////////////////
-/// Remove an existing file
+/// \brief Remove an existing file
 ///
-/// \param ftp :  Ftp instance
+/// The file name must be relative to the current working
-/// \param name : File to remove
+/// directory.
+/// Use this function with caution, the file will be
+/// removed permanently!
+///
+/// \param ftp  Ftp object
+/// \param name File to remove
 ///
 /// \return Server response to the request
 ///
@@ -421,12 +471,17 @@ CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const ch
 CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name);
 
 ////////////////////////////////////////////////////////////
-/// Download a file from the server
+/// \brief Download a file from a FTP server
 ///
-/// \param ftp :         Ftp instance
+/// The filename of the distant file is relative to the
-/// \param distantFile : Path of the distant file to download
+/// current working directory of the server, and the local
-/// \param destPath :    Where to put to file on the local computer
+/// destination path is relative to the current directory
-/// \param mode :        Transfer mode (binary by default)
+/// of your application.
+///
+/// \param ftp        Ftp object
+/// \param remoteFile Filename of the distant file to download
+/// \param localPath  Where to put to file on the local computer
+/// \param mode       Transfer mode
 ///
 /// \return Server response to the request
 ///
@@ -434,12 +489,17 @@ CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name);
 CSFML_API sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* destPath, sfFtpTransferMode mode);
 
 ////////////////////////////////////////////////////////////
-/// Upload a file to the server
+/// \brief Upload a file to a FTP server
 ///
-/// \param ftp :       Ftp instance
+/// The name of the local file is relative to the current
-/// \param localFile : Path of the local file to upload
+/// working directory of your application, and the
-/// \param destPath :  Where to put to file on the server
+/// remote path is relative to the current directory of the
-/// \param mode :      Transfer mode (binary by default)
+/// FTP server.
+///
+/// \param ftp        Ftp object
+/// \param localFile  Path of the local file to upload
+/// \param remotePath Where to put to file on the server
+/// \param mode       Transfer mode
 ///
 /// \return Server response to the request
 ///

include/SFML/Network/Http.h

@@ -33,7 +33,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Enumerate the available HTTP methods for a request
+/// \brief Enumerate the available HTTP methods for a request
+///
 ////////////////////////////////////////////////////////////
 enum sfHttpMethod
 {
@@ -44,8 +45,8 @@ enum sfHttpMethod
 
 
 ////////////////////////////////////////////////////////////
-/// Enumerate all the valid status codes returned in
+/// \brief Enumerate all the valid status codes for a response
-/// a HTTP response
+///
 ////////////////////////////////////////////////////////////
 enum sfHttpStatus
 {
@@ -80,175 +81,213 @@ enum sfHttpStatus
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new Http request
+/// \brief Create a new HTTP request
 ///
-/// \return Pointer to the new Http request
+/// \return A new sfHttpRequest object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfHttpRequest* sfHttpRequest_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Http request
+/// \brief Destroy a HTTP request
 ///
-/// \param httpRequest : Http request to destroy
+/// \param httpRequest HTTP request to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_Destroy(sfHttpRequest* httpRequest);
 
 ////////////////////////////////////////////////////////////
-/// Set the value of a field; the field is added if it doesn't exist
+/// \brief Set the value of a header field of a HTTP request
 ///
-/// \param httpRequest : Http request to modify
+/// The field is created if it doesn't exist. The name of
-/// \param field :       Name of the field to set (case-insensitive)
+/// the field is case insensitive.
-/// \param value :       Value of the field
+/// By default, a request doesn't contain any field (but the
+/// mandatory fields are added later by the HTTP client when
+/// sending the request).
+///
+/// \param httpRequest HTTP request
+/// \param field       Name of the field to set
+/// \param value       Value of the field
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const char* value);
 
 ////////////////////////////////////////////////////////////
-/// Set the request method.
+/// \brief Set a HTTP request method
-/// This parameter is sfHttpGet by default
 ///
-/// \param httpRequest : Http request to modify
+/// See the sfHttpMethod enumeration for a complete list of all
-/// \param method :      Method to use for the request
+/// the availale methods.
+/// The method is sfHttpGet by default.
+///
+/// \param httpRequest HTTP request
+/// \param method      Method to use for the request
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method);
 
 ////////////////////////////////////////////////////////////
-/// Set the target URI of the request.
+/// \brief Set a HTTP request URI
-/// This parameter is "/" by default
 ///
-/// \param httpRequest : Http request to modify
+/// The URI is the resource (usually a web page or a file)
-/// \param URI :         URI to request, local to the host
+/// that you want to get or post.
+/// The URI is "/" (the root page) by default.
+///
+/// \param httpRequest HTTP request
+/// \param uri         URI to request, relative to the host
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri);
 
 ////////////////////////////////////////////////////////////
-/// Set the HTTP version of the request.
+/// \brief Set the HTTP version of a HTTP request
-/// This parameter is 1.0 by default
 ///
-/// \param httpRequest : Http request to modify
+/// The HTTP version is 1.0 by default.
-/// \param major :       Major version number
+///
-/// \param minor :       Minor version number
+/// \param httpRequest HTTP request
+/// \param major       Major HTTP version number
+/// \param minor       Minor HTTP version number
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major, unsigned int minor);
 
 ////////////////////////////////////////////////////////////
-/// Set the body of the request. This parameter is optional and
+/// \brief Set the body of a HTTP request
-/// makes sense only for POST requests.
-/// This parameter is empty by default
 ///
-/// \param httpRequest : Http request to modify
+/// The body of a request is optional and only makes sense
-/// \param body :        Content of the request body
+/// for POST requests. It is ignored for all other methods.
+/// The body is empty by default.
+///
+/// \param httpRequest HTTP request
+/// \param body        Content of the body
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Http response
+/// \brief Destroy a HTTP response
 ///
-/// \param httpResponse : Http response to destroy
+/// \param httpResponse HTTP response to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttpResponse_Destroy(sfHttpResponse* httpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the value of a field; returns NULL if the field doesn't exist
+/// \brief Get the value of a field of a HTTP response
 ///
-/// \param httpResponse : Http response
+/// If the field \a field is not found in the response header,
-/// \param field :        Field to get
+/// the empty string is returned. This function uses
+/// case-insensitive comparisons.
 ///
-/// \return Value of the field (NULL if it doesn't exist)
+/// \param httpResponse HTTP response
+/// \param field        Name of the field to get
+///
+/// \return Value of the field, or empty string if not found
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const char* field);
 
 ////////////////////////////////////////////////////////////
-/// Get the status of a response
+/// \brief Get the status code of a HTTP reponse
 ///
-/// \param httpResponse : Http response
+/// The status code should be the first thing to be checked
+/// after receiving a response, it defines whether it is a
+/// success, a failure or anything else (see the sfHttpStatus
+/// enumeration).
 ///
-/// \return Status of the response
+/// \param httpResponse HTTP response
+///
+/// \return Status code of the response
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the major HTTP version of a response
+/// \brief Get the major HTTP version number of a HTTP response
 ///
-/// \param httpResponse : Http response
+/// \param httpResponse HTTP response
 ///
-/// \return HTTP major version of the response
+/// \return Major HTTP version number
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the minor HTTP version of a response
+/// \brief Get the minor HTTP version number of a HTTP response
 ///
-/// \param httpResponse : Http response
+/// \param httpResponse HTTP response
 ///
-/// \return HTTP minor version of the response
+/// \return Minor HTTP version number
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Get the body of the response. The body can contain :
+/// \brief Get the body of a HTTP response
-/// - the requested page (for GET requests)
-/// - a response from the server (for POST requests)
-/// - nothing (for HEAD requests)
-/// - an error message (in case of an error)
 ///
-/// \param httpResponse : Http response
+/// The body of a response may contain:
+/// \li the requested page (for GET requests)
+/// \li a response from the server (for POST requests)
+/// \li nothing (for HEAD requests)
+/// \li an error message (in case of an error)
 ///
-/// \return Body of the response (empty string if no body)
+/// \param httpResponse HTTP response
+///
+/// \return The response body
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse);
 
 ////////////////////////////////////////////////////////////
-/// Construct a new Http object
+/// \brief Create a new Http object
 ///
-/// \return Pointer to the new Http
+/// \return A new sfHttp object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfHttp* sfHttp_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing Http object
+/// \brief Destroy a Http object
 ///
-/// \param Http : Http to destroy
+/// \param http Http object to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttp_Destroy(sfHttp* http);
 
 ////////////////////////////////////////////////////////////
-/// Set the target host of a Http server
+/// \brief Set the target host of a HTTP object
 ///
-/// \param http : Http object
+/// This function just stores the host address and port, it
-/// \param host : Web server to connect to
+/// doesn't actually connect to it until you send a request.
-/// \param port : Port to use for connection (0 to use the standard port of the protocol used)
+/// If the port is 0, it means that the HTTP client will use
+/// the right port according to the protocol used
+/// (80 for HTTP, 443 for HTTPS). You should
+/// leave it like this unless you really need a port other
+/// than the standard one, or use an unknown protocol.
+///
+/// \param http Http object
+/// \param host Web server to connect to
+/// \param port Port to use for connection
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port);
 
 ////////////////////////////////////////////////////////////
-/// Send a HTTP request and return the server's response.
+/// \brief Send a HTTP request and return the server's response.
-/// You must be connected to a host before sending requests.
+///
-/// Any missing mandatory header field will be added with an appropriate value.
+/// You must have a valid host before sending a request (see sfHttp_SetHost).
-/// Warning : this function waits for the server's response and may
+/// Any missing mandatory header field in the request will be added
+/// with an appropriate value.
+/// Warning: this function waits for the server's response and may
 /// not return instantly; use a thread if you don't want to block your
-/// application.
+/// application, or use a timeout to limit the time to wait. A value
+/// of 0 means that the client will use the system defaut timeout
+/// (which is usually pretty long).
 ///
-/// \param http :    Http object
+/// \param http    Http object
-/// \param request : Request to send
+/// \param request Request to send
-/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
+/// \param timeout Maximum time to wait, in milliseconds
 ///
-/// \return Server's response, or NULL if request is invalid
+/// \return Server's response
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfHttpResponse* sfHttp_SendRequest(sfHttp* http, const sfHttpRequest* request, sfUint32 timeout);

include/SFML/Network/IpAddress.h

@@ -32,7 +32,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// sfIpAddress provides easy manipulation of IP v4 addresses
+/// \brief Encapsulate an IPv4 network address
+///
 ////////////////////////////////////////////////////////////
 typedef struct
 {
@@ -41,22 +42,30 @@ typedef struct
 
 
 ////////////////////////////////////////////////////////////
-/// Construct an address from a string
+/// \brief Create an address from a string
 ///
-/// \param string : IP address ("xxx.xxx.xxx.xxx") or network name
+/// Here \a address can be either a decimal address
+/// (ex: "192.168.1.56") or a network name (ex: "localhost").
+///
+/// \param address IP address or network name
 ///
 /// \return Resulting address
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
+CSFML_API sfIpAddress sfIpAddress_FromString(const char* address);
 
 ////////////////////////////////////////////////////////////
-/// Construct an address from 4 bytes
+/// \brief Create an address from 4 bytes
 ///
-/// \param byte0 : First byte of the address
+/// Calling sfIpAddress_FromBytes(a, b, c, d) is equivalent
-/// \param byte1 : Second byte of the address
+/// to calling sfIpAddress_FromString("a.b.c.d"), but safer
-/// \param byte2 : Third byte of the address
+/// as it doesn't have to parse a string to get the address
-/// \param byte3 : Fourth byte of the address
+/// components.
+///
+/// \param byte0 First byte of the address
+/// \param byte1 Second byte of the address
+/// \param byte2 Third byte of the address
+/// \param byte3 Fourth byte of the address
 ///
 /// \return Resulting address
 ///
@@ -64,55 +73,88 @@ CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
 CSFML_API sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3);
 
 ////////////////////////////////////////////////////////////
-/// Construct the address from a 32-bits integer
+/// \brief Construct an address from a 32-bits integer
 ///
-/// \param address : 4 bytes of the address packed into a 32-bits integer
+/// This function uses the internal representation of
+/// the address directly. It should be used for optimization
+/// purposes, and only if you got that representation from
+/// sfIpAddress_ToInteger.
+///
+/// \param address 4 bytes of the address packed into a 32-bits integer
+///
+/// \return Resulting address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_FromInteger(sfUint32 address);
 
 ////////////////////////////////////////////////////////////
-/// Get a string representation of an address
+/// \brief Get a string representation of an address
 ///
-/// \param address : Address to convert
+/// The returned string is the decimal representation of the
-/// \param string :  Char array to fill (size must be >= 16)
+/// IP address (like "192.168.1.56"), even if it was constructed
+/// from a host name.
+///
+/// \param address Address object
+///
+/// \return String representation of the address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfIpAddress_ToString(sfIpAddress address, char* string);
 
 ////////////////////////////////////////////////////////////
-/// Get an integer representation of the address
+/// \brief Get an integer representation of the address
 ///
-/// \param address : Address to convert
+/// The returned number is the internal representation of the
+/// address, and should be used for optimization purposes only
+/// (like sending the address through a socket).
+/// The integer produced by this function can then be converted
+/// back to a sfIpAddress with sfIpAddress_FromInteger.
 ///
-/// \return 32-bits integer containing the 4 bytes of the address, in system endianness
+/// \param address Address object
+///
+/// \return 32-bits unsigned integer representation of the address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfUint32 sfIpAddress_ToInteger(sfIpAddress address);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's local IP address (from the LAN point of view)
+/// \brief Get the computer's local address
 ///
-/// \return Local IP address
+/// The local address is the address of the computer from the
+/// LAN point of view, i.e. something like 192.168.1.56. It is
+/// meaningful only for communications over the local network.
+/// Unlike sfIpAddress_GetPublicAddress, this function is fast
+/// and may be used safely anywhere.
+///
+/// \return Local IP address of the computer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_GetLocalAddress(void);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's public IP address (from the web point of view).
+/// \brief Get the computer's public address
+///
+/// The public address is the address of the computer from the
+/// internet point of view, i.e. something like 89.54.1.169.
+/// It is necessary for communications over the world wide web.
 /// The only way to get a public address is to ask it to a
-/// distant website ; as a consequence, this function may be
+/// distant website; as a consequence, this function depends on
-/// very slow -- use it as few as possible !
+/// both your network connection and the server, and may be
+/// very slow. You should use it as few as possible. Because
+/// this function depends on the network connection and on a distant
+/// server, you may use a time limit if you don't want your program
+/// to be possibly stuck waiting in case there is a problem; use
+/// 0 to deactivate this limit.
 ///
-/// \param timeout : Maximum time to wait, in milliseconds (use 0 for no timeout)
+/// \param timeout Maximum time to wait, in milliseconds
 ///
-/// \return Public IP address
+/// \return Public IP address of the computer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's loopback address
+/// \brief Get the computer's loopback address
 ///
 /// \return Local host IP address (127.0.0.1, or "localhost")
 ///
@@ -120,7 +162,7 @@ CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
 CSFML_API sfIpAddress sfIpAddress_LocalHost(void);
 
 ////////////////////////////////////////////////////////////
-/// Get the empty/invalid address
+/// \brief Get the empty/invalid address
 ///
 /// \return Empty object that represents invalid addresses
 ///

include/SFML/Network/Packet.h

@@ -34,7 +34,7 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new empty packet
+/// \brief Create a new packet
 ///
 /// \return A new sfPacket object
 ///
@@ -42,47 +42,52 @@
 CSFML_API sfPacket* sfPacket_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Copy an existing packet
+/// \brief Create a new packet by copying an existing one
 ///
-/// \param packet : Packet to copy
+/// \param packet Packet to copy
 ///
-/// \return Copied object
+/// \return A new sfPacket object which is a copy of \a packet
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfPacket* sfPacket_Copy(sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing packet
+/// \brief Destroy a packet
 ///
-/// \param packet : Packet to delete
+/// \param packet Packet to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfPacket_Destroy(sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Append data to the end of a packet
+/// \brief Append data to the end of a packet
 ///
-/// \param packet :      Packet to fill
+/// \param packet      Packet object
-/// \param data :        Pointer to the bytes to append
+/// \param data        Pointer to the sequence of bytes to append
-/// \param sizeInBytes : Number of bytes to append
+/// \param sizeInBytes Number of bytes to append
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes);
 
 ////////////////////////////////////////////////////////////
-/// Clear all the data of a packet
+/// \brief Clear a packet
 ///
-/// \param packet : Packet to clear
+/// After calling Clear, the packet is empty.
+///
+/// \param packet Packet object
 ///
 ///////////////////////////////////////////////////////////
 CSFML_API void sfPacket_Clear(sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Get a pointer to the data contained in a packet
+/// \brief Get a pointer to the data contained in a packet
-/// Warning : the returned pointer may be invalid after you
-/// append data to the packet
 ///
-/// \param packet : Packet to get data from
+/// Warning: the returned pointer may become invalid after
+/// you append data to the packet, therefore it should never
+/// be stored.
+/// The return pointer is NULL if the packet is empty.
+///
+/// \param packet Packet object
 ///
 /// \return Pointer to the data
 ///
@@ -90,9 +95,12 @@ CSFML_API void sfPacket_Clear(sfPacket* packet);
 CSFML_API const char* sfPacket_GetData(const sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Get the size of the data contained in a packet
+/// \brief Get the size of the data contained in a packet
 ///
-/// \param packet : Packet to get data size from
+/// This function returns the number of bytes pointed to by
+/// what sfPacket_GetData returns.
+///
+/// \param packet Packet object
 ///
 /// \return Data size, in bytes
 ///
@@ -100,19 +108,29 @@ CSFML_API const char* sfPacket_GetData(const sfPacket* packet);
 CSFML_API size_t sfPacket_GetDataSize(const sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Tell if the reading position has reached the end of the packet
+/// \brief Tell if the reading position has reached the
+///        end of a packet
 ///
-/// \param packet : Packet to check
+/// This function is useful to know if there is some data
+/// left to be read, without actually reading it.
 ///
-/// \return sfTrue if all data have been read into the packet
+/// \param packet Packet object
+///
+/// \return sfTrue if all data was read, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Return the validity of packet
+/// \brief Test the validity of a packet, for reading
 ///
-/// \param packet : Packet to check
+/// This function allows to test the packet, to check if
+/// a reading operation was successful.
+///
+/// A packet will be in an invalid state if it has no more
+/// data to read.
+///
+/// \param packet Packet object
 ///
 /// \return sfTrue if last data extraction from packet was successful
 ///
@@ -120,9 +138,9 @@ CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet);
 CSFML_API sfBool sfPacket_CanRead(const sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Functions to extract data from a packet
+/// \brief Functions to extract data from a packet
 ///
-/// \param packet : Packet to read
+/// \param packet Packet object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool   sfPacket_ReadBool(sfPacket* packet);
@@ -138,9 +156,9 @@ CSFML_API void     sfPacket_ReadString(sfPacket* packet, char* string);
 CSFML_API void     sfPacket_ReadWideString(sfPacket* packet, wchar_t* string);
 
 ////////////////////////////////////////////////////////////
-/// Functions to insert data into a packet
+/// \brief Functions to insert data into a packet
 ///
-/// \param packet : Packet to write
+/// \param packet Packet object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfPacket_WriteBool(sfPacket* packet, sfBool);

include/SFML/Network/SocketSelector.h

@@ -33,36 +33,40 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new selector
+/// \brief Create a new selector
 ///
-/// \return A new sfSelector object
+/// \return A new sfSocketSelector object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketSelector* sfSocketSelector_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Copy an existing selector
+/// \brief Create a new socket selector by copying an existing one
 ///
-/// \param selector : Selector to copy
+/// \param selector Socket selector to copy
 ///
-/// \return Copied object
+/// \return A new sfSocketSelector object which is a copy of \a selector
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing selector
+/// \brief Destroy a socket selector
 ///
-/// \param selector : Selector to delete
+/// \param selector Socket selector to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSocketSelector_Destroy(sfSocketSelector* selector);
 
 ////////////////////////////////////////////////////////////
-/// Add a socket to watch to a selector
+/// \brief Add a new socket to a socket selector
 ///
-/// \param selector : Selector to add the socket to
+/// This function keeps a weak pointer to the socket,
-/// \param socket :   Socket to add
+/// so you have to make sure that the socket is not destroyed
+/// while it is stored in the selector.
+///
+/// \param selector Socket selector object
+/// \param socket   Pointer to the socket to add
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSocketSelector_AddTcpListener(sfSocketSelector* selector, sfTcpListener* socket);
@@ -70,10 +74,13 @@ CSFML_API void sfSocketSelector_AddTcpSocket(sfSocketSelector* selector, sfTcpSo
 CSFML_API void sfSocketSelector_AddUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Remove a socket from a selector
+/// \brief Remove a socket from a socket selector
 ///
-/// \param selector : Selector to remove the socket from
+/// This function doesn't destroy the socket, it simply
-/// \param socket :   Socket to remove
+/// removes the pointer that the selector has to it.
+///
+/// \param selector Socket selector object
+/// \param socket   POointer to the socket to remove
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSocketSelector_RemoveTcpListener(sfSocketSelector* selector, sfTcpListener* socket);
@@ -81,20 +88,28 @@ CSFML_API void sfSocketSelector_RemoveTcpSocket(sfSocketSelector* selector, sfTc
 CSFML_API void sfSocketSelector_RemoveUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Remove all sockets from a selector
+/// \brief Remove all the sockets stored in a selector
 ///
-/// \param selector : Selector to remove the socket from
+/// This function doesn't destroy any instance, it simply
+/// removes all the pointers that the selector has to
+/// external sockets.
+///
+/// \param selector Socket selector object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector);
 
 ////////////////////////////////////////////////////////////
-/// Wait and collect sockets which are ready for reading.
+/// \brief Wait until one or more sockets are ready to receive
-/// This functions will return either when at least one socket
-/// is ready, or when the given timeout is over
 ///
-/// \param selector : Selector to check
+/// This function returns as soon as at least one socket has
-/// \param timeout :  Maximum time to wait, in milliseconds (0 to disable timeout)
+/// some data available to be received. To know which sockets are
+/// ready, use the sfSocketSelector_IsXxxReady functions.
+/// If you use a timeout and no socket is ready before the timeout
+/// is over, the function returns sfFalse.
+///
+/// \param selector Socket selector object
+/// \param timeout  Maximum time to wait, in milliseconds (use 0 for infinity)
 ///
 /// \return sfTrue if there are sockets ready, sfFalse otherwise
 ///
@@ -102,12 +117,19 @@ CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector);
 CSFML_API sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout);
 
 ////////////////////////////////////////////////////////////
-/// Test a socket to know if it is ready to receive data
+/// \brief Test a socket to know if it is ready to receive data
 ///
-/// \param selector : Selector to check
+/// This function must be used after a call to
-/// \param socket :   Socket to test
+/// sfSocketSelector_Wait, to know which sockets are ready to
+/// receive data. If a socket is ready, a call to Receive will
+/// never block because we know that there is data available to read.
+/// Note that if this function returns sfTrue for a sfTcpListener,
+/// this means that it is ready to accept a new connection.
 ///
-/// \return sfTrue if the socket is ready to receive data
+/// \param selector Socket selector object
+/// \param socket   Socket to test
+///
+/// \return sfTrue if the socket is ready to read, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSocketSelector_IsTcpListenerReady(const sfSocketSelector* selector, sfTcpListener* socket);

include/SFML/Network/SocketStatus.h

@@ -27,15 +27,15 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Define the status that can be returned by the socket
+/// \brief Define the status that can be returned by the socket functions
-/// functions
+///
 ////////////////////////////////////////////////////////////
 typedef enum
 {
-    sfSocketDone,
+    sfSocketDone,         ///< The socket has sent / received the data
-    sfSocketNotReady,
+    sfSocketNotReady,     ///< The socket is not ready to send / receive data yet
-    sfSocketDisconnected,
+    sfSocketDisconnected, ///< The TCP socket has been disconnected
-    sfSocketError
+    sfSocketError         ///< An unexpected error happened
 
 } sfSocketStatus;
 

include/SFML/Network/TcpListener.h

@@ -34,64 +34,91 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new TCP socket
+/// \brief Create a new TCP listener
 ///
-/// \return Pointer to the new socket
+/// \return A new sfTcpListener object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfTcpListener* sfTcpListener_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing TCP socket
+/// \brief Destroy a TCP listener
 ///
-/// \param socket : Socket to destroy
+/// \param listener TCP listener to destroy
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API void sfTcpListener_Destroy(sfTcpListener* socket);
+CSFML_API void sfTcpListener_Destroy(sfTcpListener* listener);
 
 ////////////////////////////////////////////////////////////
-/// Change the blocking state of a TCP socket.
+/// \brief Set the blocking state of a TCP listener
-/// The default behaviour of a socket is blocking
 ///
-/// \param socket :   Socket to modify
+/// In blocking mode, calls will not return until they have
-/// \param blocking : Pass sfTrue to set the socket as blocking, or sfFalse for non-blocking
+/// completed their task. For example, a call to
+/// sfTcpListener_Accept in blocking mode won't return until
+/// a new connection was actually received.
+/// In non-blocking mode, calls will always return immediately,
+/// using the return code to signal whether there was data
+/// available or not.
+/// By default, all sockets are blocking.
+///
+/// \param listener TCP listener object
+/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* socket, sfBool blocking);
+CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* listener, sfBool blocking);
 
 ////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
+/// \brief Tell whether a TCP listener is in blocking or non-blocking mode
 ///
-/// \param socket : Socket to read
+/// \param listener TCP listener object
 ///
-/// \Return sfTrue if the socket is blocking, sfFalse otherwise
+/// \return sfTrue if the socket is blocking, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* socket);
+CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* listener);
 
 ////////////////////////////////////////////////////////////
-/// Listen to a specified port for incoming data or connections
+/// \brief Get the port to which a TCP listener is bound locally
 ///
-/// \param socket : Socket to use for listening
+/// If the socket is not listening to a port, this function
-/// \param port :   Port to listen to
+/// returns 0.
 ///
-/// \return Socket status
+/// \param listener TCP listener object
+///
+/// \return Port to which the TCP listener is bound
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* socket, unsigned short port);
+CSFML_API unsigned short sfTcpListener_GetLocalPort(const sfTcpListener* listener);
 
 ////////////////////////////////////////////////////////////
-/// Wait for a connection (must be listening to a port).
+/// \brief Start listening for connections
-/// This function is blocking, ie. it won't return before
-/// a connection has been accepted
 ///
-/// \param socket :    Socket to use for accepting
+/// This functions makes the socket listen to the specified
-/// \param connected : Pointer to a socket pointer that will be filled with the connected client
+/// port, waiting for new connections.
+/// If the socket was previously listening to another port,
+/// it will be stopped first and bound to the new port.
 ///
-/// \return Socket status
+/// \param listener TCP listener object
+/// \param port     Port to listen for new connections
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* socket, sfTcpSocket** connected);
+CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* listener, unsigned short port);
+
+////////////////////////////////////////////////////////////
+/// \brief Accept a new connection
+///
+/// If the socket is in blocking mode, this function will
+/// not return until a connection is actually received.
+///
+/// \param listener  TCP listener object
+/// \param connected Socket that will hold the new connection
+///
+/// \return Status code
+///
+////////////////////////////////////////////////////////////
+CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* listener, sfTcpSocket** connected);
 
 
 #endif // SFML_TCPLISTENER_H

include/SFML/Network/TcpSocket.h

@@ -36,45 +36,55 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new TCP socket
+/// \brief Create a new TCP socket
 ///
-/// \return Pointer to the new socket
+/// \return A new sfTcpSocket object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfTcpSocket* sfTcpSocket_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing TCP socket
+/// \brief Destroy a TCP socket
 ///
-/// \param socket : Socket to destroy
+/// \param socket TCP socket to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfTcpSocket_Destroy(sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Change the blocking state of a TCP socket.
+/// \brief Set the blocking state of a TCP listener
-/// The default behaviour of a socket is blocking
 ///
-/// \param socket :   Socket to modify
+/// In blocking mode, calls will not return until they have
-/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking
+/// completed their task. For example, a call to
+/// sfTcpSocket_Receive in blocking mode won't return until
+/// new data was actually received.
+/// In non-blocking mode, calls will always return immediately,
+/// using the return code to signal whether there was data
+/// available or not.
+/// By default, all sockets are blocking.
+///
+/// \param socket   TCP socket object
+/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking);
 
 ////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
+/// \brief Tell whether a TCP socket is in blocking or non-blocking mode
 ///
-/// \param socket : Socket to read
+/// \param socket TCP socket object
 ///
-/// \Return sfTrue if the socket is blocking, sfFalse otherwise
+/// \return sfTrue if the socket is blocking, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Get the port to which a socket is bound locally
+/// \brief Get the port to which a TCP socket is bound locally
 ///
-/// \param socket : Socket to read
+/// If the socket is not connected, this function returns 0.
+///
+/// \param socket TCP socket object
 ///
 /// \return Port to which the socket is bound
 ///
@@ -82,9 +92,12 @@ CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket);
 CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Get the address of the connected peer of a socket
+/// \brief Get the address of the connected peer of a TCP socket
 ///
-/// \param socket : Socket to read
+/// It the socket is not connected, this function returns
+/// sfIpAddress_None().
+///
+/// \param socket TCP socket object
 ///
 /// \return Address of the remote peer
 ///
@@ -92,9 +105,12 @@ CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket);
 CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Get the port of the connected peer to which a socket is connected
+/// \brief Get the port of the connected peer to which
+///        a TCP socket is connected
 ///
-/// \param socket : Socket to read
+/// If the socket is not connected, this function returns 0.
+///
+/// \param socket TCP socket object
 ///
 /// \return Remote port to which the socket is connected
 ///
@@ -102,69 +118,89 @@ CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket);
 CSFML_API unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Connect a TCP socket to another computer on a specified port
+/// \brief Connect a TCP socket to a remote peer
 ///
-/// \param socket :  Socket to connect
+/// In blocking mode, this function may take a while, especially
-/// \param host :    IP Address of the host to connect to
+/// if the remote peer is not reachable. The last parameter allows
-/// \param port :    Port to use for transfers (warning : ports < 1024 are reserved)
+/// you to stop trying to connect after a given timeout.
-/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
+/// If the socket was previously connected, it is first disconnected.
 ///
-/// \return sfTrue if operation has been successful
+/// \param socket        TCP socket object
+/// \param remoteAddress Address of the remote peer
+/// \param remotePort    Port of the remote peer
+/// \param timeout       Maximum time to wait, in milliseconds
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsigned short port, sfUint32 timeout);
 
 ////////////////////////////////////////////////////////////
-/// Disconnect a connect from its remote peer
+/// \brief Disconnect a TCP socket from its remote peer
 ///
-/// \param socket : Socket to disconnect
+/// This function gracefully closes the connection. If the
+/// socket is not connected, this function has no effect.
+///
+/// \param socket TCP socket object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfTcpSocket_Disconnect(sfTcpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Send an array of bytes to the host (must be connected first)
+/// \brief Send raw data to the remote peer of a TCP socket
 ///
-/// \param socket : Socket to use for sending
+/// This function will fail if the socket is not connected.
-/// \param data :   Pointer to the bytes to send
-/// \param size :   Number of bytes to send
 ///
-/// \return Socket status
+/// \param socket TCP socket object
+/// \param data   Pointer to the sequence of bytes to send
+/// \param size   Number of bytes to send
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t size);
 
 ////////////////////////////////////////////////////////////
-/// Receive an array of bytes from the host (must be connected first)
+/// \brief Receive raw data from the remote peer of a TCP socket
 ///
-/// \param socket :       Socket to use for receiving
+/// In blocking mode, this function will wait until some
-/// \param data :         Pointer to a byte array to fill (make sure it is big enough)
+/// bytes are actually received.
-/// \param maxSize :      Maximum number of bytes to read
+/// This function will fail if the socket is not connected.
-/// \param sizeReceived : Number of bytes received
 ///
-/// \return Socket status
+/// \param socket   TCP socket object
+/// \param data     Pointer to the array to fill with the received bytes
+/// \param size     Maximum number of bytes that can be received
+/// \param received This variable is filled with the actual number of bytes received
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived);
 
 ////////////////////////////////////////////////////////////
-/// Send a packet of data to the host (must be connected first)
+/// \brief Send a formatted packet of data to the remote peer of a TCP socket
 ///
-/// \param socket : Socket to use for sending
+/// This function will fail if the socket is not connected.
-/// \param packet : Packet to send
 ///
-/// \return Socket status
+/// \param socket TCP socket object
+/// \param packet Packet to send
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet);
 
 ////////////////////////////////////////////////////////////
-/// Receive a packet from the host (must be connected first)
+/// \brief Receive a formatted packet of data from the remote peer
 ///
-/// \param socket : Socket to use for receiving
+/// In blocking mode, this function will wait until the whole packet
-/// \param packet : Packet to fill with received data
+/// has been received.
+/// This function will fail if the socket is not connected.
 ///
-/// \return Socket status
+/// \param socket TCP socket object
+/// \param packet Packet to fill with the received data
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfTcpSocket_ReceivePacket(sfTcpSocket* socket, sfPacket* packet);

include/SFML/Network/UdpSocket.h

@@ -36,45 +36,56 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new UDP socket
+/// \brief Create a new UDP socket
 ///
-/// \return Pointer to the new socket
+/// \return A new sfUdpSocket object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfUdpSocket* sfUdpSocket_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing UDP socket
+/// \brief Destroy a UDP socket
 ///
-/// \param socket : Socket to destroy
+/// \param socket UDP socket to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfUdpSocket_Destroy(sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Change the blocking state of a UDP socket.
+/// \brief Set the blocking state of a UDP listener
-/// The default behaviour of a socket is blocking
 ///
-/// \param socket :   Socket to modify
+/// In blocking mode, calls will not return until they have
-/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking
+/// completed their task. For example, a call to
+/// sfUDPSocket_Receive in blocking mode won't return until
+/// new data was actually received.
+/// In non-blocking mode, calls will always return immediately,
+/// using the return code to signal whether there was data
+/// available or not.
+/// By default, all sockets are blocking.
+///
+/// \param socket   UDP socket object
+/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfUdpSocket_SetBlocking(sfUdpSocket* socket, sfBool blocking);
 
 ////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
+/// \brief Tell whether a UDP socket is in blocking or non-blocking mode
 ///
-/// \param socket : Socket to read
+/// \param socket UDP socket object
 ///
-/// \Return sfTrue if the socket is blocking, sfFalse otherwise
+/// \return sfTrue if the socket is blocking, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Get the port to which a socket is bound locally
+/// \brief Get the port to which a UDP socket is bound locally
 ///
-/// \param socket : Socket to read
+/// If the socket is not bound to a port, this function
+/// returns 0.
+///
+/// \param socket UDP socket object
 ///
 /// \return Port to which the socket is bound
 ///
@@ -82,82 +93,116 @@ CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket);
 CSFML_API unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Bind a socket to a specific port
+/// \brief Bind a UDP socket to a specific port
 ///
-/// \param socket : Socket to bind
+/// Binding the socket to a port is necessary for being
-/// \param port :   Port to bind the socket to
+/// able to receive data on that port.
+/// You can use the special value 0 to tell the
+/// system to automatically pick an available port, and then
+/// call sfUdpSocket_GetLocalPort to retrieve the chosen port.
 ///
-/// \return Socket status
+/// \param socket UDP socket object
+/// \param port   Port to bind the socket to
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port);
 
 ////////////////////////////////////////////////////////////
-/// Unbind a socket from its previous port, if any
+/// \brief Unbind a UDP socket from the local port to which it is bound
 ///
-/// \param socket : Socket to unbind
+/// The port that the socket was previously using is immediately
+/// available after this function is called. If the
+/// socket is not bound to a port, this function has no effect.
+///
+/// \param socket UDP socket object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfUdpSocket_Unbind(sfUdpSocket* socket);
 
 ////////////////////////////////////////////////////////////
-/// Send an array of bytes
+/// \brief Send raw data to a remote peer with a UDP socket
 ///
-/// \param socket :  Socket to use for sending
+/// Make sure that \a size is not greater than
-/// \param data :    Pointer to the bytes to send
+/// sfUdpSocket_MaxDatagramSize(), otherwise this function will
-/// \param size :    Number of bytes to send
+/// fail and no data will be sent.
-/// \param address : Address of the computer to send the packet to
-/// \param port :    Port to use for communication
 ///
-/// \return Socket status
+/// \param socket        UDP socket object
+/// \param data          Pointer to the sequence of bytes to send
+/// \param size          Number of bytes to send
+/// \param remoteAddress Address of the receiver
+/// \param remotePort    Port of the receiver to send the data to
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t size, sfIpAddress address, unsigned short port);
 
 ////////////////////////////////////////////////////////////
-/// Receive an array of bytes.
+/// \brief Receive raw data from a remote peer with a UDP socket
-/// This function is blocking, ie. it won't return before some
-/// bytes have been received
 ///
-/// \param socket :       Socket to use for receiving
+/// In blocking mode, this function will wait until some
-/// \param data :         Pointer to a byte array to fill (make sure it is big enough)
+/// bytes are actually received.
-/// \param maxSize :      Maximum number of bytes to read
+/// Be careful to use a buffer which is large enough for
-/// \param sizeReceived : Number of bytes received
+/// the data that you intend to receive, if it is too small
-/// \param address :      Address of the computer which sent the data
+/// then an error will be returned and *all* the data will
-/// \param port :         Port on which the remote computer sent the data
+/// be lost.
 ///
-/// \return Socket status
+/// \param socket        UDP socket object
+/// \param data          Pointer to the array to fill with the received bytes
+/// \param size          Maximum number of bytes that can be received
+/// \param received      This variable is filled with the actual number of bytes received
+/// \param remoteAddress Address of the peer that sent the data
+/// \param remotePort    Port of the peer that sent the data
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived, sfIpAddress* address, unsigned short* port);
 
 ////////////////////////////////////////////////////////////
-/// Send a packet of data
+/// \brief Send a formatted packet of data to a remote peer with a UDP socket
 ///
-/// \param socket :  Socket to use for sending
+/// Make sure that the packet size is not greater than
-/// \param packet :  Packet to send
+/// sfUdpSocket_MaxDatagramSize(), otherwise this function will
-/// \param address : Address of the computer to send the packet to
+/// fail and no data will be sent.
-/// \param port :    Port to use for communication
 ///
-/// \return Socket status
+/// \param socket        UDP socket object
+/// \param packet        Packet to send
+/// \param remoteAddress Address of the receiver
+/// \param remotePort    Port of the receiver to send the data to
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress address, unsigned short port);
 
 ////////////////////////////////////////////////////////////
-/// Receive a packet.
+/// \brief Receive a formatted packet of data from a remote peer with a UDP socket
-/// This function is blocking, ie. it won't return before a
-/// packet is received
 ///
-/// \param socket :  Socket to use for receiving
+/// In blocking mode, this function will wait until the whole packet
-/// \param packet :  Packet to fill with received data
+/// has been received.
-/// \param address : Address of the computer which sent the packet
+/// Warning: this functon doesn't properly handle mixed data
-/// \param port :    Port on which the remote computer sent the data
+/// received from multiple peers.
 ///
-/// \return Socket status
+/// \param packet        Packet to fill with the received data
+/// \param remoteAddress Address of the peer that sent the data
+/// \param remotePort    Port of the peer that sent the data
+///
+/// \return Status code
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress* address, unsigned short* port);
 
+////////////////////////////////////////////////////////////
+/// \brief Return the maximum number of bytes that can be
+///        sent in a single UDP datagram
+///
+/// \return The maximum size of a UDP datagram (message)
+///
+////////////////////////////////////////////////////////////
+CSFML_API unsigned int sfUdpSocket_MaxDatagramSize();
+
 
 #endif // SFML_UDPSOCKET_H

include/SFML/System/Clock.h

@@ -33,7 +33,7 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new clock and start it
+/// \brief Create a new clock and start it
 ///
 /// \return A new sfClock object
 ///
@@ -41,37 +41,43 @@
 CSFML_API sfClock* sfClock_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Copy an existing clock
+/// \brief Create a new clock by copying an existing one
 ///
-/// \param clock : Clock to copy
+/// \param clock Clock to copy
 ///
-/// \return Copied object
+/// \return A new sfClock object which is a copy of \a clock
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfClock* sfClock_Copy(sfClock* clock);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing clock
+/// \brief Destroy a clock
 ///
-/// \param clock : Clock to delete
+/// \param clock Clock to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfClock_Destroy(sfClock* clock);
 
 ////////////////////////////////////////////////////////////
-/// Get the time elapsed for a clock
+/// \brief Get the time elapsed in a clock
 ///
-/// \param clock : Clock to get time from
+/// This function returns the time elapsed since the last call
+/// to sfClock_Reset (or the construction of the object if
+/// sfClock_Reset has not been called).
 ///
-/// \return Elapsed time, in milliseconds
+/// \param clock Clock object
+///
+/// \return Time elapsed, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfUint32 sfClock_GetTime(const sfClock* clock);
 
 ////////////////////////////////////////////////////////////
-/// Restart a clock
+/// \brief Restart a clock
 ///
-/// \param clock : Clock to restart
+/// This function puts the time counter back to zero.
+///
+/// \param clock Clock object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfClock_Reset(sfClock* clock);

include/SFML/System/Mutex.h

@@ -33,7 +33,7 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Create a new mutex
+/// \brief Create a new mutex
 ///
 /// \return A new sfMutex object
 ///
@@ -41,25 +41,25 @@
 CSFML_API sfMutex* sfMutex_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing mutex
+/// \brief Destroy a mutex
 ///
-/// \param mutex : Mutex to delete
+/// \param mutex Mutex to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMutex_Destroy(sfMutex* mutex);
 
 ////////////////////////////////////////////////////////////
-/// Lock a mutex
+/// \brief Lock a mutex
 ///
-/// \param mutex : Mutex to lock
+/// \param mutex Mutex object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMutex_Lock(sfMutex* mutex);
 
 ////////////////////////////////////////////////////////////
-/// Unlock a mutex
+/// \brief Unlock a mutex
 ///
-/// \param mutex : Mutex to unlock
+/// \param mutex Mutex object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfMutex_Unlock(sfMutex* mutex);

include/SFML/System/Sleep.h

@@ -32,9 +32,12 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Make the current thread sleep for a given duration
+/// \brief Make the current thread sleep for a given duration
 ///
-/// \param duration : Time to sleep, in milliseconds
+/// sfSleep is the best way to block a program or one of its
+/// threads, as it doesn't consume any CPU power.
+///
+/// \param duration Time to sleep, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfSleep(sfUint32 duration);

include/SFML/System/Thread.h

@@ -33,45 +33,68 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new thread from a function pointer
+/// \brief Create a new thread from a function pointer
 ///
-/// \param function : Entry point of the thread
+/// Note: this does *not* run the thread, use sfThread_Launch.
-/// \param userData : Data to pass to the thread function
+///
+/// \param function Entry point of the thread
+/// \param userData Custom data to pass to the thread function
+///
+/// \return A new sfThread object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfThread* sfThread_Create(void (*function)(void*), void* userData);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing thread
+/// \brief Destroy a thread
 ///
-/// \param thread : Thread to delete
+/// This function calls sfThread_Wait, so that the internal thread
+/// cannot survive after the sfThread object is destroyed.
+///
+/// \param thread Thread to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfThread_Destroy(sfThread* thread);
 
 ////////////////////////////////////////////////////////////
-/// Run a thread
+/// \brief Run a thread
 ///
-/// \param thread : Thread to launch
+/// This function starts the entry point passed to the
+/// thread's constructor, and returns immediately.
+/// After this function returns, the thread's function is
+/// running in parallel to the calling code.
+///
+/// \param thread Thread object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfThread_Launch(sfThread* thread);
 
 ////////////////////////////////////////////////////////////
-/// Wait until a thread finishes
+/// \brief Wait until a thread finishes
 ///
-/// \param thread : Thread to wait for
+/// This function will block the execution until the
+/// thread's function ends.
+/// Warning: if the thread function never ends, the calling
+/// thread will block forever.
+/// If this function is called from its owner thread, it
+/// returns without doing anything.
+///
+/// \param thread Thread object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfThread_Wait(sfThread* thread);
 
 ////////////////////////////////////////////////////////////
-/// Terminate a thread
+/// \brief Terminate a thread
-/// Terminating a thread with this function is not safe,
-/// you should rather try to make the thread function
-/// terminate by itself
 ///
-/// \param thread : Thread to terminate
+/// This function immediately stops the thread, without waiting
+/// for its function to finish.
+/// Terminating a thread with this function is not safe,
+/// and can lead to local variables not being destroyed
+/// on some operating systems. You should rather try to make
+/// the thread function terminate by itself.
+///
+/// \param thread Thread object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfThread_Terminate(sfThread* thread);

include/SFML/Window/Context.h

@@ -33,26 +33,28 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new context
+/// \brief Create a new context
 ///
-/// \return New context
+/// This function activates the new context.
+///
+/// \return New sfContext object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfContext* sfContext_Create(void);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing context
+/// \brief Destroy a context
 ///
-/// \param context : Context to destroy
+/// \param context Context to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfContext_Destroy(sfContext* context);
 
 ////////////////////////////////////////////////////////////
-/// Activate or deactivate a context
+/// \brief Activate or deactivate explicitely a context
 ///
-/// \param context : Context to activate or deactivate
+/// \param context Context object
-/// \param active :  sfTrue to activate, sfFalse to deactivate
+/// \param active  sfTrue to activate, sfFalse to deactivate
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfContext_SetActive(sfContext* context, sfBool active);

include/SFML/Window/Event.h

@@ -34,7 +34,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Definition of all the event types
+/// \brief Definition of all the event types
+///
 ////////////////////////////////////////////////////////////
 typedef enum
 {
@@ -60,7 +61,8 @@ typedef enum
 
 
 ////////////////////////////////////////////////////////////
-/// Keyboard event parameters
+/// \brief Keyboard event parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfKeyEvent
 {
@@ -73,7 +75,8 @@ struct sfKeyEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Text event parameters
+/// \brief Text event parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfTextEvent
 {
@@ -82,7 +85,8 @@ struct sfTextEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Mouse move event parameters
+/// \brief Mouse move event parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfMouseMoveEvent
 {
@@ -92,7 +96,8 @@ struct sfMouseMoveEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Mouse buttons events parameters
+/// \brief Mouse buttons events parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfMouseButtonEvent
 {
@@ -103,7 +108,8 @@ struct sfMouseButtonEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Mouse wheel events parameters
+/// \brief Mouse wheel events parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfMouseWheelEvent
 {
@@ -114,7 +120,8 @@ struct sfMouseWheelEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Joystick axis move event parameters
+/// \brief Joystick axis move event parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfJoystickMoveEvent
 {
@@ -125,7 +132,8 @@ struct sfJoystickMoveEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Joystick buttons events parameters
+/// \brief Joystick buttons events parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfJoystickButtonEvent
 {
@@ -135,7 +143,8 @@ struct sfJoystickButtonEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Joystick connection/disconnection event parameters
+/// \brief Joystick connection/disconnection event parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfJoystickConnectEvent
 {
@@ -144,7 +153,8 @@ struct sfJoystickConnectEvent
 };
 
 ////////////////////////////////////////////////////////////
-/// Size events parameters
+/// \brief Size events parameters
+///
 ////////////////////////////////////////////////////////////
 struct sfSizeEvent
 {
@@ -155,7 +165,8 @@ struct sfSizeEvent
 
 
 ////////////////////////////////////////////////////////////
-/// sfEvent defines a system event and its parameters
+/// \brief sfEvent defines a system event and its parameters
+///
 ////////////////////////////////////////////////////////////
 typedef union
 {

include/SFML/Window/VideoMode.h

@@ -32,9 +32,10 @@
 
 
 ////////////////////////////////////////////////////////////
-/// sfVideoMode defines a video mode (width, height, bpp, frequency)
+/// \brief sfVideoMode defines a video mode (width, height, bpp, frequency)
-/// and provides functions for getting modes supported
+///        and provides functions for getting modes supported
-/// by the display device
+///        by the display device
+///
 ////////////////////////////////////////////////////////////
 typedef struct
 {
@@ -45,7 +46,7 @@ typedef struct
 
 
 ////////////////////////////////////////////////////////////
-/// Get the current desktop video mode
+/// \brief Get the current desktop video mode
 ///
 /// \return Current desktop video mode
 ///
@@ -53,23 +54,33 @@ typedef struct
 CSFML_API sfVideoMode sfVideoMode_GetDesktopMode(void);
 
 ////////////////////////////////////////////////////////////
-/// Get all the supported video modes for fullscreen mode.
+/// \brief Retrieve all the video modes supported in fullscreen mode
-/// Modes are sorted from best to worst.
 ///
-/// \param Count : Variable that will be filled with the number of modes
+/// When creating a fullscreen window, the video mode is restricted
+/// to be compatible with what the graphics driver and monitor
+/// support. This function returns the complete list of all video
+/// modes that can be used in fullscreen mode.
+/// The returned array is sorted from best to worst, so that
+/// the first element will always give the best mode (higher
+/// width, height and bits-per-pixel).
 ///
-/// \return Pointer to an array of \a count video modes
+/// \param count Pointer to a variable that will be filled with the number of modes in the array
+///
+/// \return Pointer to an array containing all the supported fullscreen modes
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count);
 
 ////////////////////////////////////////////////////////////
-/// Tell whether or not a video mode is supported
+/// \brief Tell whether or not a video mode is valid
 ///
-/// \param mode : Video mode to check
+/// The validity of video modes is only relevant when using
+/// fullscreen windows; otherwise any video mode can be used
+/// with no restriction.
 ///
+/// \param mode Video mode
 ///
-/// \return True if video mode is supported, false otherwise
+/// \return sfTrue if the video mode is valid for fullscreen mode
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfVideoMode_IsValid(sfVideoMode mode);

include/SFML/Window/Window.h

@@ -36,7 +36,7 @@
 
 
 ////////////////////////////////////////////////////////////
-/// Enumeration of window creation styles
+/// \brief Enumeration of window creation styles
 ///
 ////////////////////////////////////////////////////////////
 enum
@@ -51,7 +51,8 @@ enum
 
 
 ////////////////////////////////////////////////////////////
-/// Structure defining the window's creation settings
+/// \brief Structure defining the window's creation settings
+///
 ////////////////////////////////////////////////////////////
 typedef struct
 {
@@ -64,53 +65,89 @@ typedef struct
 
 
 ////////////////////////////////////////////////////////////
-/// Construct a new window
+/// \brief Construct a new window
 ///
-/// \param mode :     Video mode to use
+/// This function creates the window with the size and pixel
-/// \param title :    Title of the window
+/// depth defined in \a mode. An optional style can be passed to
-/// \param style :    Window style
+/// customize the look and behaviour of the window (borders,
-/// \param settings : Creation settings (pass NULL to use default values)
+/// title bar, resizable, closable, ...). If \a style contains
+/// sfFullscreen, then \a mode must be a valid video mode.
+///
+/// The fourth parameter is a pointer to a structure specifying
+/// advanced OpenGL context settings such as antialiasing,
+/// depth-buffer bits, etc.
+///
+/// \param mode     Video mode to use (defines the width, height and depth of the rendering area of the window)
+/// \param title    Title of the window
+/// \param style    Window style
+/// \param settings Additional settings for the underlying OpenGL context
+///
+/// \return A new sfWindow object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long style, const sfContextSettings* settings);
 
 ////////////////////////////////////////////////////////////
-/// Construct a window from an existing control
+/// \brief Construct a window from an existing control
 ///
-/// \param handle :   Platform-specific handle of the control
+/// Use this constructor if you want to create an OpenGL
-/// \param settings : Creation settings (pass NULL to use default values)
+/// rendering area into an already existing control.
+///
+/// The second parameter is a pointer to a structure specifying
+/// advanced OpenGL context settings such as antialiasing,
+/// depth-buffer bits, etc.
+///
+/// \param handle   Platform-specific handle of the control
+/// \param settings Additional settings for the underlying OpenGL context
+///
+/// \return A new sfWindow object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettings* settings);
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing window
+/// \brief Destroy a window
 ///
-/// \param window : Window to destroy
+/// \param window Window to destroy
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_Destroy(sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Close a window (but doesn't destroy the internal data)
+/// \brief Close a window and destroy all the attached resources
 ///
-/// \param window : Window to close
+/// After calling this function, the sfWindow object remains
+/// valid, you must call sfWindow_Destroy to actually delete it.
+/// All other functions such as sfWindow_PollEvent or sfWindow_Display
+/// will still work (i.e. you don't have to test sfWindow_IsOpened
+/// every time), and will have no effect on closed windows.
+///
+/// \param window Window object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_Close(sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Tell whether or not a window is opened
+/// \brief Tell whether or not a window is opened
 ///
-/// \param window : Window object
+/// This function returns whether or not the window exists.
+/// Note that a hidden window (sfWindow_Show(sfFalse)) will return
+/// sfTrue.
+///
+/// \param window Window object
+///
+/// \return sfTrue if the window is opened, sfFalse if it has been closed
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Get the width of the rendering region of a window
+/// \brief Get the width of the rendering region of a window
 ///
-/// \param window : Window object
+/// The width doesn't include the titlebar and borders
+/// of the window.
+///
+/// \param window Window object
 ///
 /// \return Width in pixels
 ///
@@ -118,9 +155,12 @@ CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window);
 CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Get the height of the rendering region of a window
+/// \brief Get the height of the rendering region of a window
 ///
-/// \param window : Window object
+/// The height doesn't include the titlebar and borders
+/// of the window.
+///
+/// \param window Window object
 ///
 /// \return Height in pixels
 ///
@@ -128,169 +168,233 @@ CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window);
 CSFML_API unsigned int sfWindow_GetHeight(const sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Get the creation settings of a window
+/// \brief Get the settings of the OpenGL context of a window
 ///
-/// \param window : Window object
+/// Note that these settings may be different from what was
+/// passed to the sfWindow_Create function,
+/// if one or more settings were not supported. In this case,
+/// SFML chose the closest match.
 ///
-/// \return Settings used to create the window
+/// \param window Window object
+///
+/// \return Structure containing the OpenGL context settings
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfContextSettings sfWindow_GetSettings(const sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Get the event on top of events stack of a window, if any, and pop it
+/// \brief Pop the event on top of events stack, if any, and return it
 ///
-/// \param window : Window object
+/// This function is not blocking: if there's no pending event then
-/// \param event :  Event to fill, if any
+/// it will return false and leave \a event unmodified.
+/// Note that more than one event may be present in the events stack,
+/// thus you should always call this function in a loop
+/// to make sure that you process every pending event.
 ///
-/// \return sfTrue if an event was returned, sfFalse if events stack was empty
+/// \param window Window object
+/// \param event  Event to be returned
+///
+/// \return sfTrue if an event was returned, or sfFalse if the events stack was empty
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event);
 
 ////////////////////////////////////////////////////////////
-/// Wait for an event and return it
+/// \brief Wait for an event and return it
 ///
-/// \param window : Window object
+/// This function is blocking: if there's no pending event then
-/// \param event :  Event to fill
+/// it will wait until an event is received.
+/// After this function returns (and no error occured),
+/// the \a event object is always valid and filled properly.
+/// This function is typically used when you have a thread that
+/// is dedicated to events handling: you want to make this thread
+/// sleep as long as no new event is received.
 ///
-/// \return sfFalse if an error occured
+/// \param window Window object
+/// \param event  Event to be returned
+///
+/// \return sfFalse if any error occured
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event);
 
 ////////////////////////////////////////////////////////////
-/// Enable / disable vertical synchronization on a window
+/// \brief Enable or disable vertical synchronization
 ///
-/// \param window :  Window object
+/// Activating vertical synchronization will limit the number
-/// \param enabled : sfTrue to enable v-sync, sfFalse to deactivate
+/// of frames displayed to the refresh rate of the monitor.
+/// This can avoid some visual artifacts, and limit the framerate
+/// to a good value (but not constant across different computers).
+///
+/// \param window  Window object
+/// \param enabled sfTrue to enable v-sync, sfFalse to deactivate
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled);
 
 ////////////////////////////////////////////////////////////
-/// Show or hide the mouse cursor on a window
+/// \brief Show or hide the mouse cursor
 ///
-/// \param window : Window object
+/// \param window Window object
-/// \param show :   sfTrue to show, sfFalse to hide
+/// \param show   sfTrue to show, sfFalse to hide
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show);
 
 ////////////////////////////////////////////////////////////
-/// Change the position of a window on screen.
+/// \brief Change the position of a window on screen
-/// Only works for top-level windows
 ///
-/// \param window : Window object
+/// This function only works for top-level windows
-/// \param left :   Left position
+/// (i.e. it will be ignored for windows created from
-/// \param top :    Top position
+/// the handle of a child window/control).
+///
+/// \param window Window object
+/// \param x      Left position
+/// \param y      Top position
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetPosition(sfWindow* window, int left, int top);
 
 ////////////////////////////////////////////////////////////
-/// Change the size of the rendering region of a window
+/// \brief Change the size of the rendering region of a window
 ///
-/// \param window : Window object
+/// \param window Window object
-/// \param width :  New Width
+/// \param width  New width, in pixels
-/// \param height : New Height
+/// \param height New height, in pixels
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height);
 
 ////////////////////////////////////////////////////////////
-/// Change the title of a window
+/// \brief Change the title of a window
 ///
-/// \param window : Window object
+/// \param window Window object
-/// \param title :  New title
+/// \param title  New title
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetTitle(sfWindow* window, const char* title);
 
 ////////////////////////////////////////////////////////////
-/// Show or hide a window
+/// \brief Show or hide a window
 ///
-/// \param window : Window object
+/// \param window Window object
-/// \param show :   sfTrue to show, sfFalse to hide
+/// \param show   sfTrue to show, sfFalse to hide
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_Show(sfWindow* window, sfBool show);
 
 ////////////////////////////////////////////////////////////
-/// Enable or disable automatic key-repeat for keydown events.
+/// \brief Enable or disable automatic key-repeat
-/// Automatic key-repeat is enabled by default
 ///
-/// \param window :  Window object
+/// If key repeat is enabled, you will receive repeated
-/// \param enabled : sfTrue to enable, sfFalse to disable
+/// KeyPress events while keeping a key pressed. If it is disabled,
+/// you will only get a single event when the key is pressed.
+///
+/// Key repeat is enabled by default.
+///
+/// \param window  Window object
+/// \param enabled sfTrue to enable, sfFalse to disable
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled);
 
 ////////////////////////////////////////////////////////////
-/// Change the window's icon
+/// \brief Change a window's icon
 ///
-/// \param window : Window object
+/// \a pixels must be an array of \a width x \a height pixels
-/// \param width :  Icon's width, in pixels
+/// in 32-bits RGBA format.
-/// \param height : Icon's height, in pixels
+///
-/// \param pixels : Pointer to the pixels in memory, format must be RGBA 32 bits
+/// \param window Window object
+/// \param width  Icon's width, in pixels
+/// \param height Icon's height, in pixels
+/// \param pixels Pointer to the array of pixels in memory
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, const sfUint8* pixels);
 
 ////////////////////////////////////////////////////////////
-/// Activate or deactivate a window as the current target for rendering
+/// \brief Activate or deactivate a window as the current target
+///        for OpenGL rendering
 ///
-/// \param window : Window object
+/// A window is active only on the current thread, if you want to
-/// \param active : sfTrue to activate, sfFalse to deactivate
+/// make it active on another thread you have to deactivate it
+/// on the previous thread first if it was active.
+/// Only one window can be active on a thread at a time, thus
+/// the window previously active (if any) automatically gets deactivated.
 ///
-/// \return True if operation was successful, false otherwise
+/// \param window Window object
+/// \param active sfTrue to activate, sfFalse to deactivate
+///
+/// \return sfTrue if operation was successful, sfFalse otherwise
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfWindow_SetActive(sfWindow* window, sfBool active);
 
 ////////////////////////////////////////////////////////////
-/// Display a window on screen
+/// \brief Display on screen what has been rendered to the
+///        window so far
 ///
-/// \param window : Window object
+/// This function is typically called after all OpenGL rendering
+/// has been done for the current frame, in order to show
+/// it on screen.
+///
+/// \param window Window object
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_Display(sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Limit the framerate to a maximum fixed frequency for a window
+/// \brief Limit the framerate to a maximum fixed frequency
 ///
-/// \param window : Window object
+/// If a limit is set, the window will use a small delay after
-/// \param limit :  Framerate limit, in frames per seconds (use 0 to disable limit)
+/// each call to sfWindow_Display to ensure that the current frame
+/// lasted long enough to match the framerate limit.
+///
+/// \param window Window object
+/// \param limit  Framerate limit, in frames per seconds (use 0 to disable limit)
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit);
 
 ////////////////////////////////////////////////////////////
-/// Get time elapsed since last frame of a window
+/// \brief Get the duration of the last frame
 ///
-/// \param window : Window object
+/// This function returns the time elapsed between the last
+/// two calls to sfWindow_Display.
+/// This can be useful for calculating the framerate, or for
+/// updating the application's objects.
 ///
-/// \return Time elapsed, in milliseconds
+/// \param window Window object
+///
+/// \return Time elapsed in last frame, in milliseconds
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfUint32 sfWindow_GetFrameTime(const sfWindow* window);
 
 ////////////////////////////////////////////////////////////
-/// Change the joystick threshold, ie. the value below which
+/// \brief Change the joystick threshold
-/// no move event will be generated
 ///
-/// \param window :    Window object
+/// The joystick threshold is the value below which
-/// \param threshold : New threshold, in range [0, 100]
+/// no JoyMoved event will be generated.
+///
+/// \param window    Window object
+/// \param threshold New threshold, in the range [0, 100]
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold);
 
 ////////////////////////////////////////////////////////////
-/// Retrieve the Os-specific handle of a window
+/// \brief Get the OS-specific handle of the window
 ///
-/// \param window : Window object
+/// The type of the returned handle is sfWindowHandle,
+/// which is a typedef to the handle type defined by the OS.
+/// You shouldn't need to use this function, unless you have
+/// very specific stuff to implement that SFML doesn't support,
+/// or implement a temporary workaround until a bug is fixed.
 ///
-/// \return Window handle
+/// \param window Window object
+///
+/// \return System handle of the window
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfWindowHandle sfWindow_GetSystemHandle(const sfWindow* window);

src/SFML/Audio/Listener.cpp

@@ -30,8 +30,6 @@
 
 
 
-////////////////////////////////////////////////////////////
-/// Change the global volume of all the sounds
 ////////////////////////////////////////////////////////////
 void sfListener_SetGlobalVolume(float volume)
 {
@@ -39,8 +37,6 @@ void sfListener_SetGlobalVolume(float volume)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current value of the global volume of all the sounds
 ////////////////////////////////////////////////////////////
 float sfListener_GetGlobalVolume(void)
 {
@@ -48,8 +44,6 @@ float sfListener_GetGlobalVolume(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the position of the listener
 ////////////////////////////////////////////////////////////
 void sfListener_SetPosition(float x, float y, float z)
 {
@@ -57,8 +51,6 @@ void sfListener_SetPosition(float x, float y, float z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current position of the listener
 ////////////////////////////////////////////////////////////
 void sfListener_GetPosition(float* x, float* y, float* z)
 {
@@ -72,8 +64,6 @@ void sfListener_GetPosition(float* x, float* y, float* z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the orientation of the listener
 ////////////////////////////////////////////////////////////
 void sfListener_SetDirection(float x, float y, float z)
 {
@@ -81,8 +71,6 @@ void sfListener_SetDirection(float x, float y, float z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current orientation of the listener
 ////////////////////////////////////////////////////////////
 void sfListener_GetDirection(float* x, float* y, float* z)
 {

src/SFML/Audio/Music.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Create a new music and load it from a file
 ////////////////////////////////////////////////////////////
 sfMusic* sfMusic_CreateFromFile(const char* filename)
 {
@@ -46,8 +44,6 @@ sfMusic* sfMusic_CreateFromFile(const char* filename)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a new music and load it from a file in memory
 ////////////////////////////////////////////////////////////
 sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes)
 {
@@ -62,8 +58,6 @@ sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a new music and load it from a custom stream
 ////////////////////////////////////////////////////////////
 sfMusic* sfMusic_CreateFromStream(sfInputStream* stream)
 {
@@ -81,8 +75,6 @@ sfMusic* sfMusic_CreateFromStream(sfInputStream* stream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing music
 ////////////////////////////////////////////////////////////
 void sfMusic_Destroy(sfMusic* music)
 {
@@ -90,8 +82,6 @@ void sfMusic_Destroy(sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set a music loop state
 ////////////////////////////////////////////////////////////
 void sfMusic_SetLoop(sfMusic* music, sfBool loop)
 {
@@ -99,8 +89,6 @@ void sfMusic_SetLoop(sfMusic* music, sfBool loop)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not a music is looping
 ////////////////////////////////////////////////////////////
 sfBool sfMusic_GetLoop(const sfMusic* music)
 {
@@ -108,8 +96,6 @@ sfBool sfMusic_GetLoop(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a music duration
 ////////////////////////////////////////////////////////////
 sfUint32 sfMusic_GetDuration(const sfMusic* music)
 {
@@ -117,8 +103,6 @@ sfUint32 sfMusic_GetDuration(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Start playing a music
 ////////////////////////////////////////////////////////////
 void sfMusic_Play(sfMusic* music)
 {
@@ -126,8 +110,6 @@ void sfMusic_Play(sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Pause a music
 ////////////////////////////////////////////////////////////
 void sfMusic_Pause(sfMusic* music)
 {
@@ -135,8 +117,6 @@ void sfMusic_Pause(sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop playing a music
 ////////////////////////////////////////////////////////////
 void sfMusic_Stop(sfMusic* music)
 {
@@ -144,8 +124,6 @@ void sfMusic_Stop(sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of channels of a music (1 = mono, 2 = stereo)
 ////////////////////////////////////////////////////////////
 unsigned int sfMusic_GetChannelsCount(const sfMusic* music)
 {
@@ -153,8 +131,6 @@ unsigned int sfMusic_GetChannelsCount(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the stream sample rate of a music
 ////////////////////////////////////////////////////////////
 unsigned int sfMusic_GetSampleRate(const sfMusic* music)
 {
@@ -162,8 +138,6 @@ unsigned int sfMusic_GetSampleRate(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the status of a music (stopped, paused, playing)
 ////////////////////////////////////////////////////////////
 sfSoundStatus sfMusic_GetStatus(const sfMusic* music)
 {
@@ -173,8 +147,6 @@ sfSoundStatus sfMusic_GetStatus(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current playing position of a music
 ////////////////////////////////////////////////////////////
 sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music)
 {
@@ -182,8 +154,6 @@ sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the pitch of a music
 ////////////////////////////////////////////////////////////
 void sfMusic_SetPitch(sfMusic* music, float pitch)
 {
@@ -191,8 +161,6 @@ void sfMusic_SetPitch(sfMusic* music, float pitch)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the volume of a music
 ////////////////////////////////////////////////////////////
 void sfMusic_SetVolume(sfMusic* music, float volume)
 {
@@ -200,8 +168,6 @@ void sfMusic_SetVolume(sfMusic* music, float volume)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the position of a music
 ////////////////////////////////////////////////////////////
 void sfMusic_SetPosition(sfMusic* music, float x, float y, float z)
 {
@@ -209,10 +175,6 @@ void sfMusic_SetPosition(sfMusic* music, float x, float y, float z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make the music's position relative to the listener's
-/// position, or absolute.
-/// The default value is false (absolute)
 ////////////////////////////////////////////////////////////
 void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative)
 {
@@ -220,10 +182,6 @@ void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
-/// the listener will hear the music at its maximum volume.
-/// The default minimum distance is 1.0
 ////////////////////////////////////////////////////////////
 void sfMusic_SetMinDistance(sfMusic* music, float distance)
 {
@@ -231,10 +189,6 @@ void sfMusic_SetMinDistance(sfMusic* music, 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 sfMusic_SetAttenuation(sfMusic* music, float attenuation)
 {
@@ -242,8 +196,6 @@ void sfMusic_SetAttenuation(sfMusic* music, float attenuation)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the current playing position of a stream
 ////////////////////////////////////////////////////////////
 void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset)
 {
@@ -251,8 +203,6 @@ void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the pitch of a music
 ////////////////////////////////////////////////////////////
 float sfMusic_GetPitch(const sfMusic* music)
 {
@@ -260,8 +210,6 @@ float sfMusic_GetPitch(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the volume of a music
 ////////////////////////////////////////////////////////////
 float sfMusic_GetVolume(const sfMusic* music)
 {
@@ -269,8 +217,6 @@ float sfMusic_GetVolume(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the position of a music
 ////////////////////////////////////////////////////////////
 void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z)
 {
@@ -286,9 +232,6 @@ void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the music's position is relative to the listener's
-/// position, or if it's absolute
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music)
 {
@@ -296,8 +239,6 @@ CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the minimum distance of a music
 ////////////////////////////////////////////////////////////
 float sfMusic_GetMinDistance(const sfMusic* music)
 {
@@ -305,8 +246,6 @@ float sfMusic_GetMinDistance(const sfMusic* music)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a music
 ////////////////////////////////////////////////////////////
 float sfMusic_GetAttenuation(const sfMusic* music)
 {

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

src/SFML/Audio/SoundBuffer.cpp

@@ -27,11 +27,10 @@
 ////////////////////////////////////////////////////////////
 #include <SFML/Audio/SoundBuffer.h>
 #include <SFML/Audio/SoundBufferStruct.h>
+#include <SFML/CallbackStream.h>
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from a file
 ////////////////////////////////////////////////////////////
 sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename)
 {
@@ -47,8 +46,6 @@ sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from a file in memory
 ////////////////////////////////////////////////////////////
 sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInBytes)
 {
@@ -64,10 +61,24 @@ sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInByt
 }
 
 
+
 ////////////////////////////////////////////////////////////
-/// Create a new sound buffer and load it from an array of
+CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromStream(sfInputStream* stream)
-/// samples in memory - assumed format for samples is
+{
-/// 16 bits signed integer
+    CSFML_CHECK_RETURN(stream, NULL);
+
+    sfSoundBuffer* buffer = new sfSoundBuffer;
+    CallbackStream sfmlStream(stream);
+    if (!buffer->This.LoadFromStream(sfmlStream))
+    {
+        delete buffer;
+        buffer = NULL;
+    }
+
+    return buffer;
+}
+
+
 ////////////////////////////////////////////////////////////
 sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate)
 {
@@ -83,8 +94,6 @@ sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t sa
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy an existing sound buffer
 ////////////////////////////////////////////////////////////
 sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer)
 {
@@ -94,8 +103,6 @@ sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing sound buffer
 ////////////////////////////////////////////////////////////
 void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer)
 {
@@ -103,8 +110,6 @@ void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save a sound buffer to a file
 ////////////////////////////////////////////////////////////
 sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* filename)
 {
@@ -112,8 +117,6 @@ sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* fi
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the samples contained in a sound buffer
 ////////////////////////////////////////////////////////////
 const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer)
 {
@@ -121,8 +124,6 @@ const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of samples contained in a sound buffer
 ////////////////////////////////////////////////////////////
 size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer)
 {
@@ -130,8 +131,6 @@ size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound buffer
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer)
 {
@@ -139,8 +138,6 @@ unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of channels of a sound buffer (1 = mono, 2 = stereo, ...)
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer)
 {
@@ -148,8 +145,6 @@ unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the duration of a sound buffer
 ////////////////////////////////////////////////////////////
 sfUint32 sfSoundBuffer_GetDuration(const sfSoundBuffer* soundBuffer)
 {

src/SFML/Audio/SoundBufferRecorder.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new sound buffer recorder
 ////////////////////////////////////////////////////////////
 sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void)
 {
@@ -39,8 +37,6 @@ sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing sound buffer recorder
 ////////////////////////////////////////////////////////////
 void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder)
 {
@@ -48,9 +44,6 @@ void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Start the capture.
-/// Warning : only one capture can happen at the same time
 ////////////////////////////////////////////////////////////
 void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, unsigned int sampleRate)
 {
@@ -58,8 +51,6 @@ void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, uns
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop the capture
 ////////////////////////////////////////////////////////////
 void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder)
 {
@@ -67,8 +58,6 @@ void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound buffer recorder
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* soundBufferRecorder)
 {
@@ -76,9 +65,6 @@ unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* so
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sound buffer containing the captured audio data
-/// of a sound buffer recorder
 ////////////////////////////////////////////////////////////
 const sfSoundBuffer* sfSoundBufferRecorder_GetBuffer(const sfSoundBufferRecorder* soundBufferRecorder)
 {

src/SFML/Audio/SoundRecorder.cpp

@@ -30,9 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new sound recorder with callback functions
-/// for processing captured samples
 ////////////////////////////////////////////////////////////
 sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback   onStart,
                                         sfSoundRecorderProcessCallback onProcess,
@@ -43,8 +40,6 @@ sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback   onStart,
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing sound recorder
 ////////////////////////////////////////////////////////////
 void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder)
 {
@@ -52,9 +47,6 @@ void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Start the capture.
-/// Warning : only one capture can happen at the same time
 ////////////////////////////////////////////////////////////
 void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRate)
 {
@@ -62,8 +54,6 @@ void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRa
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop the capture
 ////////////////////////////////////////////////////////////
 void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder)
 {
@@ -71,8 +61,6 @@ void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound recorder
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder)
 {
@@ -80,9 +68,6 @@ unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the system supports sound capture.
-/// If not, this class won't be usable
 ////////////////////////////////////////////////////////////
 sfBool sfSoundRecorder_IsAvailable(void)
 {

src/SFML/Audio/SoundStream.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new sound stream
 ////////////////////////////////////////////////////////////
 sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData,
                                     sfSoundStreamSeekCallback    onSeek,
@@ -43,8 +41,6 @@ sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData,
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_Destroy(sfSoundStream* soundStream)
 {
@@ -52,8 +48,6 @@ void sfSoundStream_Destroy(sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Start playing a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_Play(sfSoundStream* soundStream)
 {
@@ -61,8 +55,6 @@ void sfSoundStream_Play(sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Pause a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_Pause(sfSoundStream* soundStream)
 {
@@ -70,8 +62,6 @@ void sfSoundStream_Pause(sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Stop playing a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_Stop(sfSoundStream* soundStream)
 {
@@ -79,8 +69,6 @@ void sfSoundStream_Stop(sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the status of a sound stream (stopped, paused, playing)
 ////////////////////////////////////////////////////////////
 sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream)
 {
@@ -90,9 +78,6 @@ sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of channels of a sound stream
-/// (1 = mono, 2 = stereo)
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream)
 {
@@ -100,8 +85,6 @@ unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sample rate of a sound stream
 ////////////////////////////////////////////////////////////
 unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream)
 {
@@ -109,8 +92,6 @@ unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the pitch of a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch)
 {
@@ -118,8 +99,6 @@ void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the volume of a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume)
 {
@@ -127,8 +106,6 @@ void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the position of a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, float z)
 {
@@ -136,10 +113,6 @@ void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, flo
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make the sound stream's position relative to the listener's
-/// position, or absolute.
-/// The default value is false (absolute)
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool relative)
 {
@@ -147,10 +120,6 @@ void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool rela
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the minimum distance - closer than this distance,
-/// the listener will hear the sound stream at its maximum volume.
-/// The default minimum distance is 1.0
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance)
 {
@@ -158,10 +127,6 @@ void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the attenuation factor - the higher the attenuation, the
-/// more the sound stream will be attenuated with distance from listener.
-/// The default attenuation factor 1.0
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation)
 {
@@ -169,8 +134,6 @@ void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the current playing position of a stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOffset)
 {
@@ -178,8 +141,6 @@ void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOff
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set a stream loop state
 ////////////////////////////////////////////////////////////
 void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop)
 {
@@ -187,8 +148,6 @@ void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the pitch of a sound stream
 ////////////////////////////////////////////////////////////
 float sfSoundStream_GetPitch(const sfSoundStream* soundStream)
 {
@@ -196,8 +155,6 @@ float sfSoundStream_GetPitch(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the volume of a sound stream
 ////////////////////////////////////////////////////////////
 float sfSoundStream_GetVolume(const sfSoundStream* soundStream)
 {
@@ -205,8 +162,6 @@ float sfSoundStream_GetVolume(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the position of a sound stream
 ////////////////////////////////////////////////////////////
 void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float* y, float* z)
 {
@@ -219,9 +174,6 @@ void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the sound stream's position is relative to the listener's
-/// position, or if it's absolute
 ////////////////////////////////////////////////////////////
 CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundStream)
 {
@@ -229,8 +181,6 @@ CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundSt
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the minimum distance of a sound stream
 ////////////////////////////////////////////////////////////
 float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream)
 {
@@ -238,8 +188,6 @@ float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the attenuation factor of a sound stream
 ////////////////////////////////////////////////////////////
 float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream)
 {
@@ -247,8 +195,6 @@ float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not a stream is looping
 ////////////////////////////////////////////////////////////
 sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream)
 {
@@ -256,8 +202,6 @@ sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current playing position of a sound stream
 ////////////////////////////////////////////////////////////
 sfUint32 sfSoundStream_GetPlayingOffset(const sfSoundStream* soundStream)
 {

src/SFML/Network/Ftp.cpp

@@ -31,8 +31,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp directory response
 ////////////////////////////////////////////////////////////
 void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse)
 {
@@ -40,9 +38,6 @@ void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
-/// means a success
 ////////////////////////////////////////////////////////////
 sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse)
 {
@@ -50,8 +45,6 @@ sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the response status code
 ////////////////////////////////////////////////////////////
 sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListingResponse)
 {
@@ -61,8 +54,6 @@ sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListin
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
 ////////////////////////////////////////////////////////////
 const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListingResponse)
 {
@@ -72,8 +63,6 @@ const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListi
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the number of filenames in the listing
 ////////////////////////////////////////////////////////////
 size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingResponse)
 {
@@ -83,8 +72,6 @@ size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingRespo
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the Index-th filename in the directory
 ////////////////////////////////////////////////////////////
 const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpListingResponse, size_t index)
 {
@@ -94,8 +81,6 @@ const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpList
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp directory response
 ////////////////////////////////////////////////////////////
 void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse)
 {
@@ -103,9 +88,6 @@ void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse
 }
 
 
-////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
-/// means a success
 ////////////////////////////////////////////////////////////
 sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryResponse)
 {
@@ -113,8 +95,6 @@ sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryRes
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the response status code
 ////////////////////////////////////////////////////////////
 sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDirectoryResponse)
 {
@@ -124,8 +104,6 @@ sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDi
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
 ////////////////////////////////////////////////////////////
 const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpDirectoryResponse)
 {
@@ -135,8 +113,6 @@ const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpD
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the directory returned in the response
 ////////////////////////////////////////////////////////////
 const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryResponse* ftpDirectoryResponse)
 {
@@ -146,8 +122,6 @@ const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryResponse* ft
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp response
 ////////////////////////////////////////////////////////////
 void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse)
 {
@@ -155,9 +129,6 @@ void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Convenience function to check if the response status code
-/// means a success
 ////////////////////////////////////////////////////////////
 sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse)
 {
@@ -165,8 +136,6 @@ sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the response status code
 ////////////////////////////////////////////////////////////
 sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse)
 {
@@ -176,8 +145,6 @@ sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the full message contained in the response
 ////////////////////////////////////////////////////////////
 const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse)
 {
@@ -187,8 +154,6 @@ const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new Ftp
 ////////////////////////////////////////////////////////////
 sfFtp* sfFtp_Create(void)
 {
@@ -196,8 +161,6 @@ sfFtp* sfFtp_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Ftp
 ////////////////////////////////////////////////////////////
 void sfFtp_Destroy(sfFtp* ftp)
 {
@@ -205,8 +168,6 @@ void sfFtp_Destroy(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Connect to the specified FTP server
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port, sfUint32 timeout)
 {
@@ -218,8 +179,6 @@ sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port
 }
 
 
-////////////////////////////////////////////////////////////
-/// Log in using anonymous account
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp)
 {
@@ -229,8 +188,6 @@ sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Log in using a username and a password
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* password)
 {
@@ -240,8 +197,6 @@ sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* passwor
 }
 
 
-////////////////////////////////////////////////////////////
-/// Close the connection with FTP server
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp)
 {
@@ -251,8 +206,6 @@ sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send a null command just to prevent from being disconnected
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp)
 {
@@ -262,8 +215,6 @@ sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current working directory
 ////////////////////////////////////////////////////////////
 sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp)
 {
@@ -273,9 +224,6 @@ sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the contents of the given directory
-/// (subdirectories and files)
 ////////////////////////////////////////////////////////////
 sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* directory)
 {
@@ -285,8 +233,6 @@ sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* director
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the current working directory
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory)
 {
@@ -296,8 +242,6 @@ sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Go to the parent directory of the current one
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp)
 {
@@ -307,8 +251,6 @@ sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a new directory
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name)
 {
@@ -318,8 +260,6 @@ sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Remove an existing directory
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name)
 {
@@ -329,8 +269,6 @@ sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Rename a file
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newName)
 {
@@ -340,8 +278,6 @@ sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newNam
 }
 
 
-////////////////////////////////////////////////////////////
-/// Remove an existing file
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name)
 {
@@ -351,8 +287,6 @@ sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Download a file from the server
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* destPath, sfFtpTransferMode mode)
 {
@@ -364,8 +298,6 @@ sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* d
 }
 
 
-////////////////////////////////////////////////////////////
-/// Upload a file to the server
 ////////////////////////////////////////////////////////////
 sfFtpResponse* sfFtp_Upload(sfFtp* ftp, const char* localFile, const char* destPath, sfFtpTransferMode mode)
 {

src/SFML/Network/Http.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new Http request
 ////////////////////////////////////////////////////////////
 sfHttpRequest* sfHttpRequest_Create(void)
 {
@@ -39,8 +37,6 @@ sfHttpRequest* sfHttpRequest_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Http request
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_Destroy(sfHttpRequest* httpRequest)
 {
@@ -48,8 +44,6 @@ void sfHttpRequest_Destroy(sfHttpRequest* httpRequest)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the value of a field; the field is added if it doesn't exist
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const char* value)
 {
@@ -59,9 +53,6 @@ void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the request method.
-/// This parameter is sfHttpGet by default
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method)
 {
@@ -69,9 +60,6 @@ void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the target URI of the request.
-/// This parameter is "/" by default
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri)
 {
@@ -79,9 +67,6 @@ void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the HTTP version of the request.
-/// This parameter is 1.0 by default
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major, unsigned int minor)
 {
@@ -89,10 +74,6 @@ void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the body of the request. This parameter is optional and
-/// makes sense only for POST requests.
-/// This parameter is empty by default
 ////////////////////////////////////////////////////////////
 void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body)
 {
@@ -100,8 +81,6 @@ void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Http response
 ////////////////////////////////////////////////////////////
 void sfHttpResponse_Destroy(sfHttpResponse* httpResponse)
 {
@@ -109,8 +88,6 @@ void sfHttpResponse_Destroy(sfHttpResponse* httpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the value of a field; returns NULL if the field doesn't exist
 ////////////////////////////////////////////////////////////
 const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const char* field)
 {
@@ -122,8 +99,6 @@ const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const ch
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the status of a response
 ////////////////////////////////////////////////////////////
 sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse)
 {
@@ -133,8 +108,6 @@ sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the major HTTP version of a response
 ////////////////////////////////////////////////////////////
 unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse)
 {
@@ -142,8 +115,6 @@ unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the minor HTTP version of a response
 ////////////////////////////////////////////////////////////
 unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse)
 {
@@ -151,12 +122,6 @@ unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the body of the response. The body can contain :
-/// - the requested page (for GET requests)
-/// - a response from the server (for POST requests)
-/// - nothing (for HEAD requests)
-/// - an error message (in case of an error)
 ////////////////////////////////////////////////////////////
 const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse)
 {
@@ -166,8 +131,6 @@ const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new Http object
 ////////////////////////////////////////////////////////////
 sfHttp* sfHttp_Create(void)
 {
@@ -175,8 +138,6 @@ sfHttp* sfHttp_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing Http object
 ////////////////////////////////////////////////////////////
 void sfHttp_Destroy(sfHttp* http)
 {
@@ -184,8 +145,6 @@ void sfHttp_Destroy(sfHttp* http)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the target host of a Http server
 ////////////////////////////////////////////////////////////
 void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port)
 {
@@ -193,13 +152,6 @@ void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send a HTTP request and return the server's response.
-/// You must be connected to a host before sending requests.
-/// Any missing mandatory header field will be added with an appropriate value.
-/// Warning : this function waits for the server's response and may
-/// not return instantly; use a thread if you don't want to block your
-/// application.
 ////////////////////////////////////////////////////////////
 sfHttpResponse* sfHttp_SendRequest(sfHttp* http, const sfHttpRequest* request, sfUint32 timeout)
 {

src/SFML/Network/IpAddress.cpp

@@ -32,9 +32,7 @@
 
 namespace
 {
-    ////////////////////////////////////////////////////////////
+    // Helper function for converting a SFML address to a CSFML one
-    /// Helper function for converting a SFML address to a CSFML one
-    ////////////////////////////////////////////////////////////
     sfIpAddress FromSFMLAddress(sf::IpAddress address)
     {
         sfIpAddress result;
@@ -43,9 +41,7 @@ namespace
         return result;
     }
 
-    ////////////////////////////////////////////////////////////
+    // Helper function for converting a CSFML address to a SFML one
-    /// Helper function for converting a CSFML address to a SFML one
-    ////////////////////////////////////////////////////////////
     sf::IpAddress ToSFMLAddress(sfIpAddress address)
     {
         return sf::IpAddress(address.Address);
@@ -54,16 +50,12 @@ namespace
 
 
 ////////////////////////////////////////////////////////////
-/// Construct an address from a string
+sfIpAddress sfIpAddress_FromString(const char* address)
-////////////////////////////////////////////////////////////
-sfIpAddress sfIpAddress_FromString(const char* string)
 {
-    return FromSFMLAddress(sf::IpAddress(string));
+    return FromSFMLAddress(sf::IpAddress(address));
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct an address from 4 bytes
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3)
 {
@@ -71,8 +63,6 @@ sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, s
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the address from a 32-bits integer
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_FromInteger(sfUint32 address)
 {
@@ -80,8 +70,6 @@ sfIpAddress sfIpAddress_FromInteger(sfUint32 address)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a string representation of an address
 ////////////////////////////////////////////////////////////
 void sfIpAddress_ToString(sfIpAddress address, char* string)
 {
@@ -90,8 +78,6 @@ void sfIpAddress_ToString(sfIpAddress address, char* string)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get an integer representation of the address
 ////////////////////////////////////////////////////////////
 sfUint32 sfIpAddress_ToInteger(sfIpAddress address)
 {
@@ -99,8 +85,6 @@ sfUint32 sfIpAddress_ToInteger(sfIpAddress address)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the computer's local IP address (from the LAN point of view)
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_GetLocalAddress(void)
 {
@@ -108,11 +92,6 @@ sfIpAddress sfIpAddress_GetLocalAddress(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the computer's public IP address (from the web point of view).
-/// The only way to get a public address is to ask it to a
-/// distant website ; as a consequence, this function may be
-/// very slow -- use it as few as possible !
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout)
 {
@@ -120,16 +99,12 @@ sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the computer's loopback address
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_LocalHost(void)
 {
     return FromSFMLAddress(sf::IpAddress::LocalHost);
 }
 
-////////////////////////////////////////////////////////////
-/// Get the empty/invalid address
 ////////////////////////////////////////////////////////////
 sfIpAddress sfIpAddress_None(void)
 {

src/SFML/Network/Packet.cpp

@@ -32,9 +32,7 @@
 
 namespace
 {
-    ////////////////////////////////////////////////////////////
+    // Helper function to read a variable from a packet
-    /// Helper function to read a variable from a packet
-    ////////////////////////////////////////////////////////////
     template <typename T>
     T PacketRead(sfPacket* packet)
     {
@@ -45,9 +43,7 @@ namespace
         return value;
     }
 
-    ////////////////////////////////////////////////////////////
+    // Helper function to write a variable to a packet
-    /// Helper function to write a variable to a packet
-    ////////////////////////////////////////////////////////////
     template <typename T>
     void PacketWrite(sfPacket* packet, T value)
     {
@@ -58,8 +54,6 @@ namespace
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a new empty packet
 ////////////////////////////////////////////////////////////
 sfPacket* sfPacket_Create(void)
 {
@@ -67,8 +61,6 @@ sfPacket* sfPacket_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy an existing packet
 ////////////////////////////////////////////////////////////
 sfPacket* sfPacket_Copy(sfPacket* packet)
 {
@@ -78,8 +70,6 @@ sfPacket* sfPacket_Copy(sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing packet
 ////////////////////////////////////////////////////////////
 void sfPacket_Destroy(sfPacket* packet)
 {
@@ -87,8 +77,6 @@ void sfPacket_Destroy(sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Append data to the end of a packet
 ////////////////////////////////////////////////////////////
 void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes)
 {
@@ -97,18 +85,12 @@ void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes)
 
 
 ////////////////////////////////////////////////////////////
-/// Clear all the data of a packet
-///////////////////////////////////////////////////////////
 void sfPacket_Clear(sfPacket* packet)
 {
     CSFML_CALL(packet, Clear());
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a pointer to the data contained in a packet
-/// Warning : the returned pointer may be invalid after you
-/// append data to the packet
 ////////////////////////////////////////////////////////////
 const char* sfPacket_GetData(const sfPacket* packet)
 {
@@ -116,8 +98,6 @@ const char* sfPacket_GetData(const sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the size of the data contained in a packet
 ////////////////////////////////////////////////////////////
 size_t sfPacket_GetDataSize(const sfPacket* packet)
 {
@@ -125,8 +105,6 @@ size_t sfPacket_GetDataSize(const sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell if the reading position has reached the end of the packet
 ////////////////////////////////////////////////////////////
 sfBool sfPacket_EndOfPacket(const sfPacket* packet)
 {
@@ -134,8 +112,6 @@ sfBool sfPacket_EndOfPacket(const sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check if a packet is in a valid reading state
 ////////////////////////////////////////////////////////////
 sfBool sfPacket_CanRead(const sfPacket* packet)
 {
@@ -144,11 +120,6 @@ sfBool sfPacket_CanRead(const sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Functions to extract data from a packet
-///
-/// \param Packet : Packet to read
-///
 ////////////////////////////////////////////////////////////
 sfBool   sfPacket_ReadBool(sfPacket* packet)   {return PacketRead<sfUint8>(packet);}
 sfInt8   sfPacket_ReadInt8(sfPacket* packet)   {return PacketRead<sfInt8>(packet);}
@@ -177,11 +148,6 @@ void sfPacket_ReadWideString(sfPacket* packet, wchar_t* string)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Functions to insert data into a packet
-///
-/// \param Packet : Packet to write
-///
 ////////////////////////////////////////////////////////////
 void sfPacket_WriteBool(sfPacket* packet,   sfBool value)      {PacketWrite(packet, static_cast<sfUint8>(value));}
 void sfPacket_WriteInt8(sfPacket* packet,   sfInt8 value)      {PacketWrite(packet, value);}

src/SFML/Network/SocketSelector.cpp

@@ -33,8 +33,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Create a new selector
 ////////////////////////////////////////////////////////////
 sfSocketSelector* sfSocketSelector_Create(void)
 {
@@ -42,8 +40,6 @@ sfSocketSelector* sfSocketSelector_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy an existing selector
 ////////////////////////////////////////////////////////////
 sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector)
 {
@@ -53,8 +49,6 @@ sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing selector
 ////////////////////////////////////////////////////////////
 void sfSocketSelector_Destroy(sfSocketSelector* selector)
 {
@@ -62,8 +56,6 @@ void sfSocketSelector_Destroy(sfSocketSelector* selector)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Add a socket to watch to a selector
 ////////////////////////////////////////////////////////////
 void sfSocketSelector_AddTcpListener(sfSocketSelector* selector, sfTcpListener* socket)
 {
@@ -82,8 +74,6 @@ void sfSocketSelector_AddUdpSocket(sfSocketSelector* selector, sfUdpSocket* sock
 }
 
 
-////////////////////////////////////////////////////////////
-/// Remove a socket from a selector
 ////////////////////////////////////////////////////////////
 void sfSocketSelector_RemoveTcpListener(sfSocketSelector* selector, sfTcpListener* socket)
 {
@@ -102,8 +92,6 @@ void sfSocketSelector_RemoveUdpSocket(sfSocketSelector* selector, sfUdpSocket* s
 }
 
 
-////////////////////////////////////////////////////////////
-/// Remove all sockets from a selector
 ////////////////////////////////////////////////////////////
 void sfSocketSelector_Clear(sfSocketSelector* selector)
 {
@@ -111,10 +99,6 @@ void sfSocketSelector_Clear(sfSocketSelector* selector)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait and collect sockets which are ready for reading.
-/// This functions will return either when at least one socket
-/// is ready, or when the given timeout is over
 ////////////////////////////////////////////////////////////
 sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout)
 {
@@ -122,8 +106,6 @@ sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Test a socket to know if it is ready to receive data
 ////////////////////////////////////////////////////////////
 sfBool sfSocketSelector_IsTcpListenerReady(const sfSocketSelector* selector, sfTcpListener* socket)
 {

src/SFML/Network/TcpListener.cpp

@@ -31,8 +31,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new TCP socket
 ////////////////////////////////////////////////////////////
 sfTcpListener* sfTcpListener_Create(void)
 {
@@ -41,54 +39,48 @@ sfTcpListener* sfTcpListener_Create(void)
 
 
 ////////////////////////////////////////////////////////////
-/// Destroy an existing TCP socket
+void sfTcpListener_Destroy(sfTcpListener* listener)
-////////////////////////////////////////////////////////////
-void sfTcpListener_Destroy(sfTcpListener* socket)
 {
-    delete socket;
+    delete listener;
 }
 
 
 ////////////////////////////////////////////////////////////
-/// Change the blocking state of a TCP socket.
+void sfTcpListener_SetBlocking(sfTcpListener* listener, sfBool blocking)
-/// The default behaviour of a socket is blocking
-////////////////////////////////////////////////////////////
-void sfTcpListener_SetBlocking(sfTcpListener* socket, sfBool blocking)
 {
-    CSFML_CALL(socket, SetBlocking(blocking == sfTrue));
+    CSFML_CALL(listener, SetBlocking(blocking == sfTrue));
 }
 
 
 ////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
+sfBool sfTcpListener_IsBlocking(const sfTcpListener* listener)
-////////////////////////////////////////////////////////////
-sfBool sfTcpListener_IsBlocking(const sfTcpListener* socket)
 {
-    CSFML_CALL_RETURN(socket, IsBlocking(), sfFalse);
+    CSFML_CALL_RETURN(listener, IsBlocking(), sfFalse);
 }
 
 
 ////////////////////////////////////////////////////////////
-/// Listen to a specified port for incoming data or connections
+unsigned short sfTcpListener_GetLocalPort(const sfTcpListener* listener)
-////////////////////////////////////////////////////////////
-sfSocketStatus sfTcpListener_Listen(sfTcpListener* socket, unsigned short port)
 {
-    CSFML_CHECK_RETURN(socket, sfSocketError);
+    CSFML_CALL_RETURN(listener, GetLocalPort(), 0);
-
-    return static_cast<sfSocketStatus>(socket->This.Listen(port));
 }
 
 
 ////////////////////////////////////////////////////////////
-/// Wait for a connection (must be listening to a port).
+sfSocketStatus sfTcpListener_Listen(sfTcpListener* listener, unsigned short port)
-/// This function is blocking, ie. it won't return before
-/// a connection has been accepted
-////////////////////////////////////////////////////////////
-sfSocketStatus sfTcpListener_Accept(sfTcpListener* socket, sfTcpSocket** connected)
 {
-    CSFML_CHECK_RETURN(socket, sfSocketError);
+    CSFML_CHECK_RETURN(listener, sfSocketError);
+
+    return static_cast<sfSocketStatus>(listener->This.Listen(port));
+}
+
+
+////////////////////////////////////////////////////////////
+sfSocketStatus sfTcpListener_Accept(sfTcpListener* listener, sfTcpSocket** connected)
+{
+    CSFML_CHECK_RETURN(listener, sfSocketError);
     CSFML_CHECK_RETURN(connected, sfSocketError);
 
     *connected = new sfTcpSocket;
-    return static_cast<sfSocketStatus>(socket->This.Accept((*connected)->This));
+    return static_cast<sfSocketStatus>(listener->This.Accept((*connected)->This));
 }

src/SFML/Network/TcpSocket.cpp

@@ -33,8 +33,6 @@
 #include <string.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new TCP socket
 ////////////////////////////////////////////////////////////
 sfTcpSocket* sfTcpSocket_Create(void)
 {
@@ -42,8 +40,6 @@ sfTcpSocket* sfTcpSocket_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing TCP socket
 ////////////////////////////////////////////////////////////
 void sfTcpSocket_Destroy(sfTcpSocket* socket)
 {
@@ -51,9 +47,6 @@ void sfTcpSocket_Destroy(sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the blocking state of a TCP socket.
-/// The default behaviour of a socket is blocking
 ////////////////////////////////////////////////////////////
 void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking)
 {
@@ -61,8 +54,6 @@ void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
 ////////////////////////////////////////////////////////////
 sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket)
 {
@@ -70,8 +61,6 @@ sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the port to which a socket is bound locally
 ////////////////////////////////////////////////////////////
 unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket)
 {
@@ -79,8 +68,6 @@ unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the address of the connected peer of a socket
 ////////////////////////////////////////////////////////////
 sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket)
 {
@@ -94,8 +81,6 @@ sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the port of the connected peer to which a socket is connected
 ////////////////////////////////////////////////////////////
 unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket)
 {
@@ -103,8 +88,6 @@ unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Connect a TCP socket to another computer on a specified port
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsigned short port, sfUint32 timeout)
 {
@@ -116,8 +99,6 @@ sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsign
 }
 
 
-////////////////////////////////////////////////////////////
-/// Disconnect a connect from its remote peer
 ////////////////////////////////////////////////////////////
 void sfTcpSocket_Disconnect(sfTcpSocket* socket)
 {
@@ -125,8 +106,6 @@ void sfTcpSocket_Disconnect(sfTcpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send an array of bytes to the host (must be connected first)
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t size)
 {
@@ -136,8 +115,6 @@ sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t si
 }
 
 
-////////////////////////////////////////////////////////////
-/// Receive an array of bytes from the host (must be connected first)
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived)
 {
@@ -155,8 +132,6 @@ sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSi
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send a packet of data to the host (must be connected first)
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet)
 {
@@ -167,8 +142,6 @@ sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Receive a packet from the host (must be connected first)
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfTcpSocket_ReceivePacket(sfTcpSocket* socket, sfPacket* packet)
 {

src/SFML/Network/UdpSocket.cpp

@@ -33,8 +33,6 @@
 #include <string.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new UDP socket
 ////////////////////////////////////////////////////////////
 sfUdpSocket* sfUdpSocket_Create(void)
 {
@@ -42,8 +40,6 @@ sfUdpSocket* sfUdpSocket_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing UDP socket
 ////////////////////////////////////////////////////////////
 void sfUdpSocket_Destroy(sfUdpSocket* socket)
 {
@@ -51,17 +47,12 @@ void sfUdpSocket_Destroy(sfUdpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the blocking state of a UDP socket.
-/// The default behaviour of a socket is blocking
 ////////////////////////////////////////////////////////////
 void sfUdpSocket_SetBlocking(sfUdpSocket* socket, sfBool blocking)
 {
     CSFML_CALL(socket, SetBlocking(blocking == sfTrue));
 }
 
-////////////////////////////////////////////////////////////
-/// Get the blocking state of the socket
 ////////////////////////////////////////////////////////////
 sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket)
 {
@@ -69,8 +60,6 @@ sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the port to which the socket is bound locally
 ////////////////////////////////////////////////////////////
 unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket)
 {
@@ -78,8 +67,6 @@ unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Bind a socket to a specific port
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port)
 {
@@ -89,8 +76,6 @@ sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Unbind a socket from its previous port, if any
 ////////////////////////////////////////////////////////////
 void sfUdpSocket_Unbind(sfUdpSocket* socket)
 {
@@ -98,8 +83,6 @@ void sfUdpSocket_Unbind(sfUdpSocket* socket)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send an array of bytes
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t size, sfIpAddress address, unsigned short port)
 {
@@ -112,10 +95,6 @@ sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t si
 }
 
 
-////////////////////////////////////////////////////////////
-/// Receive an array of bytes.
-/// This function is blocking, ie. it won't return before some
-/// bytes have been received
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived, sfIpAddress* address, unsigned short* port)
 {
@@ -143,8 +122,6 @@ sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSi
 }
 
 
-////////////////////////////////////////////////////////////
-/// Send a packet of data
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress address, unsigned short port)
 {
@@ -158,10 +135,6 @@ sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfI
 }
 
 
-////////////////////////////////////////////////////////////
-/// Receive a packet.
-/// This function is blocking, ie. it won't return before a
-/// packet is received
 ////////////////////////////////////////////////////////////
 sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress* address, unsigned short* port)
 {
@@ -182,3 +155,10 @@ sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet,
 
     return sfSocketDone;
 }
+
+
+////////////////////////////////////////////////////////////
+unsigned int sfUdpSocket_MaxDatagramSize()
+{
+    return sf::UdpSocket::MaxDatagramSize;
+}

src/SFML/System/Clock.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Create a new clock and start it
 ////////////////////////////////////////////////////////////
 sfClock* sfClock_Create(void)
 {
@@ -39,8 +37,6 @@ sfClock* sfClock_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy an existing clock
 ////////////////////////////////////////////////////////////
 sfClock* sfClock_Copy(sfClock* clock)
 {
@@ -50,8 +46,6 @@ sfClock* sfClock_Copy(sfClock* clock)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing clock
 ////////////////////////////////////////////////////////////
 void sfClock_Destroy(sfClock* clock)
 {
@@ -59,8 +53,6 @@ void sfClock_Destroy(sfClock* clock)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the time elapsed for a clock
 ////////////////////////////////////////////////////////////
 sfUint32 sfClock_GetTime(const sfClock* clock)
 {
@@ -68,8 +60,6 @@ sfUint32 sfClock_GetTime(const sfClock* clock)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Restart a clock
 ////////////////////////////////////////////////////////////
 void sfClock_Reset(sfClock* clock)
 {

src/SFML/System/Mutex.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Create a new mutex
 ////////////////////////////////////////////////////////////
 sfMutex* sfMutex_Create(void)
 {
@@ -39,8 +37,6 @@ sfMutex* sfMutex_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing mutex
 ////////////////////////////////////////////////////////////
 void sfMutex_Destroy(sfMutex* mutex)
 {
@@ -48,8 +44,6 @@ void sfMutex_Destroy(sfMutex* mutex)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Lock a mutex
 ////////////////////////////////////////////////////////////
 void sfMutex_Lock(sfMutex* mutex)
 {
@@ -57,8 +51,6 @@ void sfMutex_Lock(sfMutex* mutex)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Unlock a mutex
 ////////////////////////////////////////////////////////////
 void sfMutex_Unlock(sfMutex* mutex)
 {

src/SFML/System/Sleep.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Make the current thread sleep for a given duration
 ////////////////////////////////////////////////////////////
 void sfSleep(sfUint32 Duration)
 {

src/SFML/System/Thread.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new thread from a function pointer
 ////////////////////////////////////////////////////////////
 sfThread* sfThread_Create(void (*function)(void*), void* userData)
 {
@@ -39,8 +37,6 @@ sfThread* sfThread_Create(void (*function)(void*), void* userData)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing thread
 ////////////////////////////////////////////////////////////
 void sfThread_Destroy(sfThread* thread)
 {
@@ -48,8 +44,6 @@ void sfThread_Destroy(sfThread* thread)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Run a thread
 ////////////////////////////////////////////////////////////
 void sfThread_Launch(sfThread* thread)
 {
@@ -57,8 +51,6 @@ void sfThread_Launch(sfThread* thread)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait until a thread finishes
 ////////////////////////////////////////////////////////////
 void sfThread_Wait(sfThread* thread)
 {
@@ -66,11 +58,6 @@ void sfThread_Wait(sfThread* thread)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Terminate a thread
-/// Terminating a thread with this function is not safe,
-/// you should rather try to make the thread function
-/// terminate by itself
 ////////////////////////////////////////////////////////////
 void sfThread_Terminate(sfThread* thread)
 {

src/SFML/Window/Context.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new context
 ////////////////////////////////////////////////////////////
 sfContext* sfContext_Create(void)
 {
@@ -39,8 +37,6 @@ sfContext* sfContext_Create(void)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing context
 ////////////////////////////////////////////////////////////
 void sfContext_Destroy(sfContext* context)
 {
@@ -48,8 +44,6 @@ void sfContext_Destroy(sfContext* context)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Activate or deactivate a context
 ////////////////////////////////////////////////////////////
 void sfContext_SetActive(sfContext* context, sfBool active)
 {

src/SFML/Window/Joystick.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Check if a joystick is connected
 ////////////////////////////////////////////////////////////
 sfBool sfJoystick_IsConnected(unsigned int joystick)
 {
@@ -39,8 +37,6 @@ sfBool sfJoystick_IsConnected(unsigned int joystick)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the number of buttons supported by a joystick
 ////////////////////////////////////////////////////////////
 unsigned int sfJoystick_GetButtonCount(unsigned int joystick)
 {
@@ -48,8 +44,6 @@ unsigned int sfJoystick_GetButtonCount(unsigned int joystick)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check if a joystick supports a given axis
 ////////////////////////////////////////////////////////////
 sfBool sfJoystick_HasAxis(unsigned int joystick, sfJoystickAxis axis)
 {
@@ -57,8 +51,6 @@ sfBool sfJoystick_HasAxis(unsigned int joystick, sfJoystickAxis axis)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check if a joystick button is pressed
 ////////////////////////////////////////////////////////////
 sfBool sfJoystick_IsButtonPressed(unsigned int joystick, unsigned int button)
 {
@@ -66,8 +58,6 @@ sfBool sfJoystick_IsButtonPressed(unsigned int joystick, unsigned int button)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current position of a joystick axis
 ////////////////////////////////////////////////////////////
 float sfJoystick_GetAxisPosition(unsigned int joystick, sfJoystickAxis axis)
 {
@@ -75,8 +65,6 @@ float sfJoystick_GetAxisPosition(unsigned int joystick, sfJoystickAxis axis)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Update the states of all joysticks
 ////////////////////////////////////////////////////////////
 void sfJoystick_Update(void)
 {

src/SFML/Window/Keyboard.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Check if a key is pressed
 ////////////////////////////////////////////////////////////
 sfBool sfKeyboard_IsKeyPressed(sfKeyCode key)
 {

src/SFML/Window/Mouse.cpp

@@ -31,8 +31,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Check if a mouse button is pressed
 ////////////////////////////////////////////////////////////
 sfBool sfMouse_IsButtonPressed(sfMouseButton button)
 {
@@ -40,8 +38,6 @@ sfBool sfMouse_IsButtonPressed(sfMouseButton button)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current position of the mouse
 ////////////////////////////////////////////////////////////
 void sfMouse_GetPosition(int* x, int* y, const sfWindow* relativeTo)
 {
@@ -58,8 +54,6 @@ void sfMouse_GetPosition(int* x, int* y, const sfWindow* relativeTo)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current position of the mouse
 ////////////////////////////////////////////////////////////
 void sfMouse_SetPosition(int x, int y, const sfWindow* relativeTo)
 {

src/SFML/Window/VideoMode.cpp

@@ -30,8 +30,6 @@
 #include <SFML/Internal.h>
 
 
-////////////////////////////////////////////////////////////
-/// Get the current desktop video mode
 ////////////////////////////////////////////////////////////
 sfVideoMode sfVideoMode_GetDesktopMode(void)
 {
@@ -46,10 +44,7 @@ sfVideoMode sfVideoMode_GetDesktopMode(void)
 
 
 ////////////////////////////////////////////////////////////
-/// Get all the supported video modes for fullscreen mode.
+const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* count)
-/// Modes are sorted from best to worst.
-////////////////////////////////////////////////////////////
-const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count)
 {
     static std::vector<sfVideoMode> modes;
 
@@ -67,15 +62,13 @@ const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count)
         }
     }
 
-    if (Count)
+    if (count)
-        *Count = modes.size();
+        *count = modes.size();
 
     return !modes.empty() ? &modes[0] : NULL;
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not a video mode is supported
 ////////////////////////////////////////////////////////////
 sfBool sfVideoMode_IsValid(sfVideoMode mode)
 {

src/SFML/Window/Window.cpp

@@ -31,8 +31,6 @@
 #include <SFML/ConvertEvent.h>
 
 
-////////////////////////////////////////////////////////////
-/// Construct a new window
 ////////////////////////////////////////////////////////////
 sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long style, const sfContextSettings* settings)
 {
@@ -58,8 +56,6 @@ sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long sty
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct a window from an existing control
 ////////////////////////////////////////////////////////////
 sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettings* settings)
 {
@@ -82,16 +78,12 @@ sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettin
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy an existing window
 ////////////////////////////////////////////////////////////
 void sfWindow_Destroy(sfWindow* window)
 {
     delete window;
 }
 
-////////////////////////////////////////////////////////////
-/// Close a window (but doesn't destroy the internal data)
 ////////////////////////////////////////////////////////////
 void sfWindow_Close(sfWindow* window)
 {
@@ -99,8 +91,6 @@ void sfWindow_Close(sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tell whether or not a window is opened
 ////////////////////////////////////////////////////////////
 sfBool sfWindow_IsOpened(const sfWindow* window)
 {
@@ -108,8 +98,6 @@ sfBool sfWindow_IsOpened(const sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the width of the rendering region of a window
 ////////////////////////////////////////////////////////////
 unsigned int sfWindow_GetWidth(const sfWindow* window)
 {
@@ -117,8 +105,6 @@ unsigned int sfWindow_GetWidth(const sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the height of the rendering region of a window
 ////////////////////////////////////////////////////////////
 unsigned int sfWindow_GetHeight(const sfWindow* window)
 {
@@ -126,8 +112,6 @@ unsigned int sfWindow_GetHeight(const sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the creation settings of a window
 ////////////////////////////////////////////////////////////
 sfContextSettings sfWindow_GetSettings(const sfWindow* window)
 {
@@ -145,8 +129,6 @@ sfContextSettings sfWindow_GetSettings(const sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the event on top of events stack of a window, if any, and pop it
 ////////////////////////////////////////////////////////////
 sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event)
 {
@@ -168,8 +150,6 @@ sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait for an event and return it
 ////////////////////////////////////////////////////////////
 sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event)
 {
@@ -191,8 +171,6 @@ sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Enable / disable vertical synchronization on a window
 ////////////////////////////////////////////////////////////
 void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled)
 {
@@ -200,8 +178,6 @@ void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Show or hide the mouse cursor on a window
 ////////////////////////////////////////////////////////////
 void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show)
 {
@@ -209,9 +185,6 @@ void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the position of a window on screen.
-/// Only works for top-level windows
 ////////////////////////////////////////////////////////////
 void sfWindow_SetPosition(sfWindow* window, int left, int top)
 {
@@ -219,8 +192,6 @@ void sfWindow_SetPosition(sfWindow* window, int left, int top)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the size of the rendering region of a window
 ////////////////////////////////////////////////////////////
 void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height)
 {
@@ -228,8 +199,6 @@ void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the title of a window
 ////////////////////////////////////////////////////////////
 void sfWindow_SetTitle(sfWindow* window, const char* title)
 {
@@ -237,8 +206,6 @@ void sfWindow_SetTitle(sfWindow* window, const char* title)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Show or hide a window
 ////////////////////////////////////////////////////////////
 void sfWindow_Show(sfWindow* window, sfBool show)
 {
@@ -246,9 +213,6 @@ void sfWindow_Show(sfWindow* window, sfBool show)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Enable or disable automatic key-repeat for keydown events.
-/// Automatic key-repeat is enabled by default
 ////////////////////////////////////////////////////////////
 void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled)
 {
@@ -256,8 +220,6 @@ void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the window's icon
 ////////////////////////////////////////////////////////////
 void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, const sfUint8* pixels)
 {
@@ -265,8 +227,6 @@ void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height,
 }
 
 
-////////////////////////////////////////////////////////////
-/// Activate or deactivate a window as the current target for rendering
 ////////////////////////////////////////////////////////////
 sfBool sfWindow_SetActive(sfWindow* window, sfBool active)
 {
@@ -274,8 +234,6 @@ sfBool sfWindow_SetActive(sfWindow* window, sfBool active)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Display a window on screen
 ////////////////////////////////////////////////////////////
 void sfWindow_Display(sfWindow* window)
 {
@@ -283,8 +241,6 @@ void sfWindow_Display(sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Limit the framerate to a maximum fixed frequency for a window
 ////////////////////////////////////////////////////////////
 void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit)
 {
@@ -292,8 +248,6 @@ void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get time elapsed since last frame of a window
 ////////////////////////////////////////////////////////////
 sfUint32 sfWindow_GetFrameTime(const sfWindow* window)
 {
@@ -301,9 +255,6 @@ sfUint32 sfWindow_GetFrameTime(const sfWindow* window)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the joystick threshold, ie. the value below which
-/// no move event will be generated
 ////////////////////////////////////////////////////////////
 void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold)
 {
@@ -311,8 +262,6 @@ void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Retrieve the Os-specific handle of a window
 ////////////////////////////////////////////////////////////
 sfWindowHandle sfWindow_GetSystemHandle(const sfWindow* window)
 {