Improved API documentation (copied from SFML)

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
-/// \param userData : Data to pass to the thread function
+/// Note: this does *not* run the thread, use sfThread_Launch.
+///
+/// \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
-/// Terminating a thread with this function is not safe,
-/// you should rather try to make the thread function
-/// terminate by itself
+/// \brief Terminate a thread
 ///
-/// \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);