From 50a5ecd79f1ad1b3b45bdd8e795717659b2e91af Mon Sep 17 00:00:00 2001
From: groogy <groogy@4e206d99-4929-0410-ac5d-dfc041789085>
Date: Thu, 25 Nov 2010 19:30:10 +0000
Subject: [PATCH] Added rdoc comments to all audio classes.

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1714 4e206d99-4929-0410-ac5d-dfc041789085
---
 bindings/ruby/sfml-audio/audio/Music.cpp      | 21 ++++-
 bindings/ruby/sfml-audio/audio/Sound.cpp      | 79 ++++++++++++++++++
 .../ruby/sfml-audio/audio/SoundBuffer.cpp     | 29 ++++++-
 .../sfml-audio/audio/SoundBufferRecorder.cpp  | 13 +++
 .../ruby/sfml-audio/audio/SoundRecorder.cpp   | 35 ++++++++
 .../ruby/sfml-audio/audio/SoundSource.cpp     | 82 +++++++++++++++++++
 .../ruby/sfml-audio/audio/SoundStream.cpp     | 79 ++++++++++++++++++
 7 files changed, 336 insertions(+), 2 deletions(-)

diff --git a/bindings/ruby/sfml-audio/audio/Music.cpp b/bindings/ruby/sfml-audio/audio/Music.cpp
index 33e3ad860..dbcce6b35 100644
--- a/bindings/ruby/sfml-audio/audio/Music.cpp
+++ b/bindings/ruby/sfml-audio/audio/Music.cpp
@@ -34,11 +34,25 @@ static VALUE Music_Free( sf::Music *anObject )
 	delete anObject;
 }
 
+/* call-seq:
+ *   Music.new()	-> music
+ *
+ * Creates a new music instance.
+ */
 static VALUE Music_Initialize( int argc, VALUE *args, VALUE self )
 {
 	return self;
 }
 
+/* call-seq:
+ *   music.openFromFile()	-> true or false
+ *
+ * Open a music from an audio file.
+ *
+ * This function doesn't start playing the music (call Play() to do so). Here is a complete list of all the supported 
+ * audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2,
+ * caf, wve, mpc2k, rf64.
+ */
 static VALUE Music_OpenFromFile( VALUE self, VALUE aFilename )
 {
 	sf::Music *object = NULL;
@@ -53,6 +67,11 @@ static VALUE Music_OpenFromFile( VALUE self, VALUE aFilename )
 	}
 }
 
+/* call-seq:
+ *   music.getDuration()	-> float
+ *
+ * Get the total duration of the music. 
+ */
 static VALUE Music_GetDuration( VALUE self )
 {
 	sf::Music *object = NULL;
@@ -111,7 +130,7 @@ void Init_Music( void )
 	rb_define_singleton_method( globalMusicClass, "new", Music_New, -1 );
 	
 	// Instance methods
-	rb_define_method( globalMusicClass, "initialize", Music_Initialize, -1 );
+	rb_define_method( globalMusicClass, "initialize", Music_Initialize, 0 );
 	rb_define_method( globalMusicClass, "openFromFile", Music_OpenFromFile, 1 );
 	rb_define_method( globalMusicClass, "getDuration", Music_GetDuration, 0 );
 		
diff --git a/bindings/ruby/sfml-audio/audio/Sound.cpp b/bindings/ruby/sfml-audio/audio/Sound.cpp
index d92eb6b78..de66db771 100644
--- a/bindings/ruby/sfml-audio/audio/Sound.cpp
+++ b/bindings/ruby/sfml-audio/audio/Sound.cpp
@@ -37,6 +37,11 @@ static void Sound_Free( sf::Sound *anObject )
 	delete anObject;
 }
 
+/* call-seq:
+ *   Sound.new()	-> sound
+ *
+ * Creates a new sound instance.
+ */
 static VALUE Sound_Initialize( int argc, VALUE *args, VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -86,6 +91,14 @@ static VALUE Sound_Initialize( int argc, VALUE *args, VALUE self )
 	return self;
 }
 
+/* call-seq:
+ *   sound.play()
+ *
+ * Start or resume playing the sound.
+ *
+ * This function starts the sound if it was stopped, resumes it if it was paused, and does nothing it is 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.
+ */
 static VALUE Sound_Play( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -94,6 +107,13 @@ static VALUE Sound_Play( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.pause()
+ *
+ * Pause the sound.
+ *
+ * This function pauses the sound if it was playing, otherwise (sound already paused or stopped) it has no effect.
+ */
 static VALUE Sound_Pause( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -102,6 +122,14 @@ static VALUE Sound_Pause( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.stop()
+ *
+ * Stop playing the sound.
+ *
+ * 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 pause()).
+ */
 static VALUE Sound_Stop( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -110,6 +138,14 @@ static VALUE Sound_Stop( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.setBuffer( buffer )
+ *
+ * Set the source buffer containing the audio data to play.
+ *
+ * It is important to note that the sound buffer is not copied, thus the sf::SoundBuffer instance must remain alive as 
+ * long as it is attached to the sound.
+ */
 static VALUE Sound_SetBuffer( VALUE self, VALUE aBuffer )
 {
 	VALIDATE_CLASS( aBuffer, globalSoundBufferClass, "buffer" );
@@ -122,6 +158,14 @@ static VALUE Sound_SetBuffer( VALUE self, VALUE aBuffer )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.setLoop( loop )
+ *
+ * Set whether or not the sound should loop after reaching the end.
+ *
+ * If set, the sound will restart from beginning after reaching the end and so on, until it is stopped or 
+ * setLoop(false) is called. The default looping state for sound is false.
+ */
 static VALUE Sound_SetLoop( VALUE self, VALUE aLoop )
 {
 	sf::Sound *object = NULL;
@@ -141,6 +185,13 @@ static VALUE Sound_SetLoop( VALUE self, VALUE aLoop )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.setPlayingOffset( offset )
+ *
+ * Change the current playing position of the sound.
+ *
+ * The playing position can be changed when the sound is either paused or playing.
+ */
 static VALUE Sound_SetPlayingOffset( VALUE self, VALUE aOffset )
 {
 	sf::Sound *object = NULL;
@@ -149,11 +200,21 @@ static VALUE Sound_SetPlayingOffset( VALUE self, VALUE aOffset )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound.getBuffer()	-> buffer
+ *
+ * Get the audio buffer attached to the sound. 
+ */
 static VALUE Sound_GetBuffer( VALUE self )
 {
 	return rb_iv_get( self, "@__buffer_ref" );
 }
 
+/* call-seq:
+ *   sound.getLoop()	-> true or false
+ *
+ * Tell whether or not the sound is in loop mode. 
+ */
 static VALUE Sound_GetLoop( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -168,6 +229,11 @@ static VALUE Sound_GetLoop( VALUE self )
 	}
 }
 
+/* call-seq:
+ *   sound.getPlayingOffset()	-> float
+ *
+ * Get the current playing position of the sound. 
+ */
 static VALUE Sound_GetPlayingOffset( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -175,6 +241,11 @@ static VALUE Sound_GetPlayingOffset( VALUE self )
 	return rb_float_new( object->GetPlayingOffset() );
 }
 
+/* call-seq:
+ *   sound.getStatus()	-> fixnum
+ *
+ * Get the current status of the sound (stopped, paused, playing). 
+ */
 static VALUE Sound_GetStatus( VALUE self )
 {
 	sf::Sound *object = NULL;
@@ -182,6 +253,14 @@ static VALUE Sound_GetStatus( VALUE self )
 	return INT2FIX( static_cast< int >( object->GetStatus() ) );
 }
 
+/* call-seq:
+ *   sound.resetBuffer()
+ *
+ * Reset the internal buffer of the sound.
+ *
+ * This function is for internal use only, you don't have to use it. It is called by the SFML::SoundBuffer that this 
+ * sound uses, when it is destroyed in order to prevent the sound from using a dead buffer. 
+ */
 static VALUE Sound_ResetBuffer( VALUE self )
 {
 	sf::Sound *object = NULL;
diff --git a/bindings/ruby/sfml-audio/audio/SoundBuffer.cpp b/bindings/ruby/sfml-audio/audio/SoundBuffer.cpp
index a6c7898cb..9ca6f10b2 100644
--- a/bindings/ruby/sfml-audio/audio/SoundBuffer.cpp
+++ b/bindings/ruby/sfml-audio/audio/SoundBuffer.cpp
@@ -115,7 +115,7 @@ static VALUE SoundBuffer_SaveToFile( VALUE self, VALUE aFileName )
 }
 
 /* call-seq:
- *   image.getSamples()	-> array of samples
+ *   sound_buffer.getSamples()	-> array of samples
  *
  * Get the array of audio samples stored in the buffer.
  *
@@ -138,6 +138,13 @@ static VALUE SoundBuffer_GetSamples( VALUE self )
 	return samples;
 }
 
+/* call-seq:
+ *   sound_buffer.getSamplesCount()	-> fixnum
+ *
+ * Get the number of samples stored in the buffer.
+ *
+ * The array of samples can be accessed with the getSamples() function.
+ */
 static VALUE SoundBuffer_GetSamplesCount( VALUE self )
 {
 	sf::SoundBuffer *object = NULL;
@@ -145,6 +152,14 @@ static VALUE SoundBuffer_GetSamplesCount( VALUE self )
 	return INT2FIX( object->GetSamplesCount() );
 }
 
+/* call-seq:
+ *   sound_buffer.getSampleRate()	-> fixnum
+ *
+ * Get the sample rate of the sound.
+ *
+ * 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).
+ */
 static VALUE SoundBuffer_GetSampleRate( VALUE self )
 {
 	sf::SoundBuffer *object = NULL;
@@ -152,6 +167,11 @@ static VALUE SoundBuffer_GetSampleRate( VALUE self )
 	return INT2FIX( object->GetSampleRate() );
 }
 
+/* call-seq:
+ *   sound_buffer.getChannelsCount()	-> float
+ *
+ * Get the total duration of the sound. 
+ */
 static VALUE SoundBuffer_GetChannelsCount( VALUE self )
 {
 	sf::SoundBuffer *object = NULL;
@@ -159,6 +179,13 @@ static VALUE SoundBuffer_GetChannelsCount( VALUE self )
 	return INT2FIX( object->GetChannelsCount() );
 }
 
+/* call-seq:
+ *   sound_buffer.getDuration()	-> fixnum
+ *
+ * Get the number of channels used by the sound.
+ *
+ * If the sound is mono then the number of channels will be 1, 2 for stereo, etc.
+ */
 static VALUE SoundBuffer_GetDuration( VALUE self )
 {
 	sf::SoundBuffer *object = NULL;
diff --git a/bindings/ruby/sfml-audio/audio/SoundBufferRecorder.cpp b/bindings/ruby/sfml-audio/audio/SoundBufferRecorder.cpp
index b80ca9e90..786f409e9 100644
--- a/bindings/ruby/sfml-audio/audio/SoundBufferRecorder.cpp
+++ b/bindings/ruby/sfml-audio/audio/SoundBufferRecorder.cpp
@@ -103,6 +103,14 @@ static void SoundBufferRecorder_Free( rbSoundBufferRecorder * anObject )
 	delete anObject;
 }
 
+/* call-seq:
+ *   sound_buffer_recorder.getBuffer()	-> sound_buffer
+ *
+ * Get the sound buffer containing the captured audio data.
+ *
+ * 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.
+ */
 static VALUE SoundBufferRecorder_GetBuffer( VALUE self )
 {
 	sf::SoundBufferRecorder *object = NULL;
@@ -113,6 +121,11 @@ static VALUE SoundBufferRecorder_GetBuffer( VALUE self )
 	return rbData;
 }
 
+/* call-seq:
+ *   SoundBufferRecorder.new()	-> sound_buffer_recorder
+ *
+ * Creates a sound buffer recorder instance for us.
+ */
 static VALUE SoundBufferRecorder_New( int argc, VALUE *args, VALUE aKlass )
 {
 	rbSoundBufferRecorder *object = new rbSoundBufferRecorder();
diff --git a/bindings/ruby/sfml-audio/audio/SoundRecorder.cpp b/bindings/ruby/sfml-audio/audio/SoundRecorder.cpp
index 1f480de3e..2501efea2 100644
--- a/bindings/ruby/sfml-audio/audio/SoundRecorder.cpp
+++ b/bindings/ruby/sfml-audio/audio/SoundRecorder.cpp
@@ -98,6 +98,15 @@ static void SoundRecorder_Free( rbSoundRecorder * anObject )
 	delete anObject;
 }
 
+/* call-seq:
+ *   sound_recorder.start()
+ *
+ * Start the capture.
+ *
+ * The sampleRate parameter defines the number of audio samples 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.
+ */
 static VALUE SoundRecorder_Start( int argc, VALUE *args, VALUE self )
 {
 	sf::SoundRecorder *object = NULL;
@@ -116,6 +125,11 @@ static VALUE SoundRecorder_Start( int argc, VALUE *args, VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_recorder.stop()
+ *
+ * Stop the capture. 
+ */
 static VALUE SoundRecorder_Stop( VALUE self )
 {
 	sf::SoundRecorder *object = NULL;
@@ -124,6 +138,14 @@ static VALUE SoundRecorder_Stop( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_recorder.getSampleRate()	-> fixnum
+ *
+ * Get the sample rate.
+ *
+ * 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).
+ */
 static VALUE SoundRecorder_GetSampleRate( VALUE self )
 {
 	sf::SoundRecorder *object = NULL;
@@ -131,6 +153,11 @@ static VALUE SoundRecorder_GetSampleRate( VALUE self )
 	return INT2FIX( object->GetSampleRate() );
 }
 
+/* call-seq:
+ *   SoundRecorder.new()	-> sound_recorder
+ *
+ * Creates a sound recorder instance for us.
+ */
 static VALUE SoundRecorder_New( int argc, VALUE *args, VALUE aKlass )
 {
 	rbSoundRecorder *object = new rbSoundRecorder();
@@ -139,6 +166,14 @@ static VALUE SoundRecorder_New( int argc, VALUE *args, VALUE aKlass )
 	return rbData;
 }
 
+/* call-seq:
+ *   SoundRecorder.isAvailable()	-> true or false
+ *
+ * Check if the system supports audio capture.
+ *
+ * This function should always be called before using the audio capture features. If it returns false, then any attempt 
+ * to use sf::SoundRecorder or one of its derived classes will fail.
+ */
 static VALUE SoundRecorder_IsAvailable( VALUE aKlass )
 {
 	return ( sf::SoundRecorder::IsAvailable() == true ? Qtrue : Qfalse );
diff --git a/bindings/ruby/sfml-audio/audio/SoundSource.cpp b/bindings/ruby/sfml-audio/audio/SoundSource.cpp
index 695254f77..08ebd7cb2 100644
--- a/bindings/ruby/sfml-audio/audio/SoundSource.cpp
+++ b/bindings/ruby/sfml-audio/audio/SoundSource.cpp
@@ -30,6 +30,11 @@ VALUE globalSoundSourceClass;
 /* External classes */
 extern VALUE globalVector3Class;
 
+/* call-seq:
+ *   sound_source.getAttenuation()	-> float
+ *
+ * Get the attenuation factor of the sound.
+ */
 static VALUE SoundSource_GetAttenuation( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -37,6 +42,11 @@ static VALUE SoundSource_GetAttenuation( VALUE self )
 	return rb_float_new( object->GetAttenuation() );
 }
 
+/* call-seq:
+ *   sound_source.getMinDistance()	-> float
+ *
+ * Get the minimum distance of the sound.
+ */
 static VALUE SoundSource_GetMinDistance( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -44,6 +54,11 @@ static VALUE SoundSource_GetMinDistance( VALUE self )
 	return rb_float_new( object->GetMinDistance() );
 }
 
+/* call-seq:
+ *   sound_source.getPitch()	-> float
+ *
+ * Get the pitch of the sound. 
+ */
 static VALUE SoundSource_GetPitch( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -51,6 +66,11 @@ static VALUE SoundSource_GetPitch( VALUE self )
 	return rb_float_new( object->GetPitch() );
 }
 
+/* call-seq:
+ *   sound_source.getPosition()	-> vector3
+ *
+ * Get the 3D position of the sound in the audio scene. 
+ */
 static VALUE SoundSource_GetPosition( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -59,6 +79,11 @@ static VALUE SoundSource_GetPosition( VALUE self )
 	return rb_funcall( globalVector3Class, rb_intern( "new" ), 3, rb_float_new( pos.x ), rb_float_new( pos.y ), rb_float_new( pos.z ) );
 }
 
+/* call-seq:
+ *   sound_source.getVolume()	-> float
+ *
+ * Get the volume of the sound. 
+ */
 static VALUE SoundSource_GetVolume( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -66,6 +91,11 @@ static VALUE SoundSource_GetVolume( VALUE self )
 	return rb_float_new( object->GetVolume() );
 }
 
+/* call-seq:
+ *   sound_source.isRelativeToListener()	-> true or false
+ *
+ * Tell whether the sound's position is relative to the listener or is absolute. 
+ */
 static VALUE SoundSource_IsRelativeToListener( VALUE self )
 {
 	sf::SoundSource *object = NULL;
@@ -73,6 +103,16 @@ static VALUE SoundSource_IsRelativeToListener( VALUE self )
 	return ( object->IsRelativeToListener() == true ? Qtrue : Qfalse );
 }
 
+/* call-seq:
+ *   sound_source.setAttenuation( value )
+ *
+ * Set the attenuation factor of the sound.
+ *
+ * The attenuation is a multiplicative factor which makes 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.
+ */
 static VALUE SoundSource_SetAttenuation( VALUE self, VALUE aValue )
 {
 	sf::SoundSource *object = NULL;
@@ -81,6 +121,15 @@ static VALUE SoundSource_SetAttenuation( VALUE self, VALUE aValue )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_source.setMinDistance( value )
+ *
+ * Set the minimum distance of the sound.
+ *
+ * The "minimum distance" of a sound is the maximum 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.
+ */
 static VALUE SoundSource_SetMinDistance( VALUE self, VALUE aValue )
 {
 	sf::SoundSource *object = NULL;
@@ -89,6 +138,15 @@ static VALUE SoundSource_SetMinDistance( VALUE self, VALUE aValue )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_source.setPitch( value )
+ *
+ * Set the pitch of the sound.
+ *
+ * The pitch represents the perceived fundamental frequency 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.
+ */
 static VALUE SoundSource_SetPitch( VALUE self, VALUE aValue )
 {
 	sf::SoundSource *object = NULL;
@@ -97,6 +155,14 @@ static VALUE SoundSource_SetPitch( VALUE self, VALUE aValue )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_source.setPosition( x, y, z )
+ *   sound_source.setPosition( vector3 )
+ *
+ * Set the 3D position of the sound in the audio scene.
+ *
+ * Only sounds with one channel (mono sounds) can be spatialized. The default position of a sound is (0, 0, 0).
+ */
 static VALUE SoundSource_SetPosition( int argc, VALUE *args, VALUE self )
 {
 	float x, y, z;
@@ -128,6 +194,15 @@ static VALUE SoundSource_SetPosition( int argc, VALUE *args, VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_source.setRelativeToListener( value )
+ *
+ * Make the sound's position relative to the listener or absolute.
+ *
+ * Making a sound relative to the listener will ensure that it will always 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).
+ */
 static VALUE SoundSource_SetRelativeToListener( VALUE self, VALUE aValue )
 {
 	sf::SoundSource *object = NULL;
@@ -147,6 +222,13 @@ static VALUE SoundSource_SetRelativeToListener( VALUE self, VALUE aValue )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_source.setVolume( value )
+ *
+ * Set the volume of the sound.
+ *
+ * The volume is a value between 0 (mute) and 100 (full volume). The default value for the volume is 100.
+ */
 static VALUE SoundSource_SetVolume( VALUE self, VALUE aValue )
 {
 	sf::SoundSource *object = NULL;
diff --git a/bindings/ruby/sfml-audio/audio/SoundStream.cpp b/bindings/ruby/sfml-audio/audio/SoundStream.cpp
index 286c733cf..c5a64a14b 100644
--- a/bindings/ruby/sfml-audio/audio/SoundStream.cpp
+++ b/bindings/ruby/sfml-audio/audio/SoundStream.cpp
@@ -106,6 +106,14 @@ static VALUE SoundStream_Free( rbSoundStream *anObject )
 	delete anObject;
 }
 
+/* call-seq:
+ *   sound_stream.play()
+ *
+ * Start or resume playing the audio stream.
+ *
+ * This function starts the stream if it was stopped, resumes it if it was paused, and does nothing it is it already 
+ * playing. This function uses its own thread so that it doesn't block the rest of the program while the stream is played.
+ */
 static VALUE SoundStream_Play( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -114,6 +122,14 @@ static VALUE SoundStream_Play( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_stream.pause()
+ *
+ * Start or resume playing the audio stream.
+ *
+ * This function starts the stream if it was stopped, resumes it if it was paused, and does nothing it is it already 
+ * playing. This function uses its own thread so that it doesn't block the rest of the program while the stream is played.
+ */
 static VALUE SoundStream_Pause( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -122,6 +138,14 @@ static VALUE SoundStream_Pause( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_stream.stop()
+ *
+ * Stop playing the audio stream.
+ *
+ * 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 pause()).
+ */
 static VALUE SoundStream_Stop( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -130,6 +154,13 @@ static VALUE SoundStream_Stop( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_stream.getChannelsCount()	-> fixnum
+ *
+ * Return the number of channels of the stream.
+ *
+ * 1 channel means a mono sound, 2 means stereo, etc.
+ */
 static VALUE SoundStream_GetChannelsCount( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -137,6 +168,13 @@ static VALUE SoundStream_GetChannelsCount( VALUE self )
 	return INT2FIX( object->GetChannelsCount() );
 }
 
+/* call-seq:
+ *   sound_stream.getSampleRate()	-> fixnum
+ *
+ * Get the stream sample rate of the stream.
+ *
+ * The sample rate is the number of audio samples played per second. The higher, the better the quality.
+ */
 static VALUE SoundStream_GetSampleRate( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -144,6 +182,11 @@ static VALUE SoundStream_GetSampleRate( VALUE self )
 	return INT2FIX( object->GetSampleRate() );
 }
 
+/* call-seq:
+ *   sound_stream.getStatus()	-> fixnum
+ *
+ * Get the current status of the stream (stopped, paused, playing). 
+ */
 static VALUE SoundStream_GetStatus( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -151,6 +194,13 @@ static VALUE SoundStream_GetStatus( VALUE self )
 	return INT2FIX( static_cast< int >( object->GetStatus() ) );
 }
 
+/* call-seq:
+ *   sound_stream.setPlayingOffset( offset )
+ *
+ * Change the current playing position of the stream.
+ *
+ * The playing position can be changed when the stream is either paused or playing.
+ */
 static VALUE SoundStream_SetPlayingOffset( VALUE self, VALUE anOffset )
 {
 	sf::SoundStream *object = NULL;
@@ -159,6 +209,11 @@ static VALUE SoundStream_SetPlayingOffset( VALUE self, VALUE anOffset )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_stream.getPlayingOffset()	-> float
+ *
+ * Get the current playing position of the stream. 
+ */
 static VALUE SoundStream_GetPlayingOffset( VALUE self, VALUE anOffset )
 {
 	sf::SoundStream *object = NULL;
@@ -166,6 +221,14 @@ static VALUE SoundStream_GetPlayingOffset( VALUE self, VALUE anOffset )
 	return rb_float_new( object->GetPlayingOffset() );
 }
 
+/* call-seq:
+ *   sound_stream.setLoop( loop )
+ *
+ * Set whether or not the stream should loop after reaching the end.
+ *
+ * If set, the stream will restart from beginning after reaching the end and so on, until it is stopped or 
+ * SetLoop(false) is called. The default looping state for streams is false.
+ */
 static VALUE SoundStream_SetLoop( VALUE self, VALUE aLoop )
 {
 	sf::SoundStream *object = NULL;
@@ -185,6 +248,11 @@ static VALUE SoundStream_SetLoop( VALUE self, VALUE aLoop )
 	return Qnil;
 }
 
+/* call-seq:
+ *   sound_stream.getLoop() 	-> true or false
+ *
+ * Tell whether or not the stream is in loop mode. 
+ */
 static VALUE SoundStream_GetLoop( VALUE self )
 {
 	sf::SoundStream *object = NULL;
@@ -199,6 +267,17 @@ static VALUE SoundStream_GetLoop( VALUE self )
 	}
 }
 
+/* call-seq:
+ *   sound_stream.initialize()
+ *
+ * This is a direct binding to the sf::SoundStream::Initialize function.
+ *
+ * Define the audio stream parameters.
+ *
+ * This function must be called by derived classes as soon as they know the audio settings of the stream to play. Any 
+ * attempt to manipulate the stream (play(), ...) before calling this function will fail. It can be called multiple 
+ * times if the settings of the audio stream change, but only when the stream is stopped.
+ */
 static VALUE SoundStream_Initialize( VALUE self, VALUE channelsCount, VALUE sampleRate )
 {
 	rbSoundStream *object = NULL;