Improved API documentation (copied from SFML)

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.
-/// Warning : only one capture can happen at the same time
+/// \brief Start the capture of a sound recorder recorder
 ///
-/// \param soundBufferRecorder : Sound buffer recorder to start
-/// \param sampleRate :          Sound frequency (the more samples, the higher the quality)
+/// The \a 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.
+///
+/// \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
-/// of a sound buffer recorder
+/// \brief Get the sound buffer containing the captured audio data
 ///
-/// \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);