Updated the documentation for some sfml-system classes

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1203 4e206d99-4929-0410-ac5d-dfc041789085

include/SFML/System/Clock.hpp

@@ -34,20 +34,27 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Clock is an utility class for manipulating time
+/// \brief Utility class for manipulating time
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Clock
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// The clock starts automatically after being constructed.
     ///
     ////////////////////////////////////////////////////////////
     Clock();
 
     ////////////////////////////////////////////////////////////
-    /// Get the time elapsed since last reset
+    /// \brief Get the time elapsed
+    ///
+    /// This function returns the time elapsed since the last call
+    /// to Reset() (or the construction of the instance if Reset()
+    /// has not been called) in seconds.
     ///
     /// \return Time elapsed, in seconds
     ///
@@ -55,7 +62,9 @@ public :
     float GetElapsedTime() const;
 
     ////////////////////////////////////////////////////////////
-    /// Restart the timer
+    /// \brief Restart the timer
+    ///
+    /// This function puts the time counter back to zero.
     ///
     ////////////////////////////////////////////////////////////
     void Reset();
@@ -72,3 +81,23 @@ private :
 
 
 #endif // SFML_CLOCK_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Clock
+///
+/// sf::Clock is a lightweight class for measuring time.
+/// Its accuray depends on the underlying OS, but you can generally
+/// expect a 1 ms precision.
+///
+/// Usage example:
+/// \code
+/// sf::Clock clock;
+/// ...
+/// float time1 = clock.GetElapsedTime();
+/// clock.Reset();
+/// ...
+/// float time2 = clock.GetElapsedTime();
+/// \endcode
+///
+////////////////////////////////////////////////////////////

include/SFML/System/Lock.hpp

@@ -36,23 +36,27 @@ namespace sf
 class Mutex;
 
 ////////////////////////////////////////////////////////////
-/// Lock is an exception-safe automatic wrapper for
+/// \brief Automatic wrapper for locking and unlocking mutexes
-/// locking and unlocking mutexes
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Lock : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Construct the lock with a target mutex (lock it)
+    /// \brief Construct the lock with a target mutex
     ///
-    /// \param mutex : Mutex to lock
+    /// The mutex passed to sf::Lock is automatically locked.
+    ///
+    /// \param mutex Mutex to lock
     ///
     ////////////////////////////////////////////////////////////
     Lock(Mutex& mutex);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor (unlocks the mutex)
+    /// \brief Destructor
+    ///
+    /// The destructor of sf::Lock automatically unlocks its mutex.
     ///
     ////////////////////////////////////////////////////////////
     ~Lock();
@@ -69,3 +73,64 @@ private :
 
 
 #endif // SFML_LOCK_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Lock
+///
+/// sf::Lock is a RAII wrapper for sf::Mutex. By unlocking
+/// it in its destructor, it ensures that the mutex will
+/// always be released when the current scope (most likely
+/// a function) ends.
+/// This is even more important when an exception or an early
+/// return statement can interrupt the excution flow of the function.
+///
+/// For maximum robustness, sf::Lock should always be used
+/// to lock/unlock a mutex.
+///
+/// Usage example:
+/// \code
+/// sf::Mutex mutex;
+/// 
+/// void function()
+/// {
+///     sf::Lock lock(mutex); // mutex is now locked
+/// 
+///     functionThatMayThrowAnException(); // mutex is unlocked if this function throws
+/// 
+///     if (someCondition)
+///         return; // mutex is unlocked
+/// 
+/// } // mutex is unlocked
+/// \endcode
+///
+/// Because the mutex is not explicitely unlocked in the code,
+/// it may remain locked longer than needed. If the region
+/// of the code that needs to be protected by the mutex is
+/// not the entire function, a good practice is to create a
+/// smaller, inner scope so that the lock is limited to this
+/// part of the code.
+///
+/// \code
+/// sf::Mutex mutex;
+/// 
+/// void function()
+/// {
+///     {
+///       sf::Lock lock(mutex);
+///       codeThatRequiresProtection();
+/// 
+///     } // mutex is unlocked here
+/// 
+///     codeThatDoesntCareAboutTheMutex();
+/// }
+/// \endcode
+///
+/// Having a mutex locked longer than required is a bad practice
+/// which can lead to bad performances. Don't forget that when
+/// a mutex is locked, other threads may be waiting doing nothing
+/// until it ls released.
+///
+/// \see sf::Mutex
+///
+////////////////////////////////////////////////////////////

include/SFML/System/Mutex.hpp

@@ -40,35 +40,38 @@ namespace priv
 }
 
 ////////////////////////////////////////////////////////////
-/// Mutex defines a mutex (MUTual EXclusion) object,
+/// \brief Blocks concurrent access to shared resources
-/// that allows a thread to lock critical instructions
+///        from multiple threads
-/// to avoid simultaneous access with other threads.
+///
-/// See Lock for an efficient way of using it.
 ////////////////////////////////////////////////////////////
 class SFML_API Mutex : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     Mutex();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~Mutex();
 
     ////////////////////////////////////////////////////////////
-    /// Lock the mutex
+    /// \brief Lock the mutex
+    ///
+    /// If the mutex is already locked in another thread,
+    /// this call will block the execution until the mutex
+    /// is released.
     ///
     ////////////////////////////////////////////////////////////
     void Lock();
 
     ////////////////////////////////////////////////////////////
-    /// Unlock the mutex
+    /// \brief Unlock the mutex
     ///
     ////////////////////////////////////////////////////////////
     void Unlock();
@@ -85,3 +88,49 @@ private :
 
 
 #endif // SFML_MUTEX_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Mutex
+///
+/// Mutex stands for "MUTual EXclusion". A mutex is a
+/// synchronization object, used when multiple threads are involved.
+///
+/// When you want to protect a part of the code from being accessed
+/// simultaneously by multiple threads, you typically use a
+/// mutex. When a thread is locked by a thread, any other thread
+/// trying to lock it will be blocked until the mutex is released
+/// by the thread that locked it. This way, you can allow only
+/// one thread at a time to access a critical region of your code.
+///
+/// Usage example:
+/// \code
+/// Database db; // this is a critical resource that needs some protection
+/// sf::Mutex mutex;
+///
+/// void thread1()
+/// {
+///     mutex.Lock(); // this call will block the thread if the mutex is already locked by thread2
+///     db.write(...);
+///     mutex.Unlock(); // if thread2 was waiting, it will now be unblocked
+/// }
+/// 
+/// void thread2()
+/// {
+///     mutex.Lock(); // this call will block the thread if the mutex is already locked by thread1
+///     db.write(...);
+///     mutex.Unlock(); // if thread1 was waiting, it will now be unblocked
+/// }
+/// \endcode
+///
+/// Be very careful with mutexes. A bad usage can lead to bad problems,
+/// like deadlocks (two threads are waiting for each other and the
+/// application is stuck).
+///
+/// To make the usage of mutexes more robust, particularly in
+/// environments where exceptions can be thrown, you should
+/// use the helper class sf::Lock to lock/unlock mutexes.
+///
+/// \see sf::Lock
+///
+////////////////////////////////////////////////////////////

include/SFML/System/NonCopyable.hpp

@@ -34,15 +34,20 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Utility base class to easily declare non-copyable classes.
+/// \brief Utility class that makes any derived
-/// Just inherit from NonCopyable to get a non-copyable class
+///        class non-copyable
+///
 ////////////////////////////////////////////////////////////
 struct SFML_API NonCopyable
 {
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// The default constructor won't be generated, so provide it
+    /// \brief Default constructor
+    ///
+    /// Because this class has a copy constructor, the compiler
+    /// will not automatically generate the default constructor.
+    /// That's why we must define it explicitely.
     ///
     ////////////////////////////////////////////////////////////
     NonCopyable() {}
@@ -50,15 +55,25 @@ protected :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Copy constructor : declare it private and don't implement
+    /// \brief Disabled copy constructor
-    /// it to prevent from calling it
+    ///
+    /// By making the copy constructor private, the compiler will
+    /// trigger an error if anyone outside tries to use it.
+    /// To prevent NonCopyable or friend classes from using it,
+    /// we also give no definition, so that the linker will
+    /// produce an error if the first protection was inefficient.
     ///
     ////////////////////////////////////////////////////////////
     NonCopyable(const NonCopyable&);
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator : declare it private and don't implement
+    /// \brief Disabled assignment operator
-    /// it to prevent from calling it
+    ///
+    /// By making the copy constructor private, the compiler will
+    /// trigger an error if anyone outside tries to use it.
+    /// To prevent NonCopyable or friend classes from using it,
+    /// we also give no definition, so that the linker will
+    /// produce an error if the first protection was inefficient.
     ///
     ////////////////////////////////////////////////////////////
     NonCopyable& operator =(const NonCopyable&);
@@ -68,3 +83,34 @@ private :
 
 
 #endif // SFML_NONCOPYABLE_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::NonCopyable
+///
+/// This class makes its instances non-copyable, by explicitely
+/// disabling its copy constructor and its assignment operator.
+///
+/// To create a non-copyable class, simply inherit from
+/// sf::NonCopyable.
+///
+/// Because sf::NonCopyable is a struct and not a class,
+/// inheritance is public by default so that the syntax for
+/// using it is even shorter (see below).
+///
+/// Usage example:
+/// \code
+/// class MyNonCopyableClass : sf::NonCopyable
+/// {
+///     ...
+/// };
+/// \endcode
+///
+/// Deciding whether the instances of a class can be copied
+/// or not is a very important design choice. You are strongly
+/// encouraged to think about it before writing a class,
+/// and to use sf::NonCopyable when necessary to prevent
+/// many potential future errors when using it. This is also
+/// a very important indication to users of your class.
+///
+////////////////////////////////////////////////////////////

include/SFML/System/Randomizer.hpp

@@ -34,24 +34,25 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Randomizer is an utility class for generating pseudo-random
+/// \brief Utility class for generating pseudo-random numbers
-/// numbers
 ////////////////////////////////////////////////////////////
 class SFML_API Randomizer
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Set the seed for the generator. Using a known seed
+    /// \brief Set a new seed for the generator
-    /// allows you to reproduce the same sequence of random number
     ///
-    /// \param seed : Number to use as the seed
+    /// Using a known seed allows you to reproduce the same
+    /// sequence of random numbers.
+    ///
+    /// \param seed Number to use as the seed
     ///
     ////////////////////////////////////////////////////////////
     static void SetSeed(unsigned int seed);
 
     ////////////////////////////////////////////////////////////
-    /// Get the seed used to generate random numbers the generator.
+    /// \brief Get the current seed of the generator
     ///
     /// \return Current seed
     ///
@@ -59,10 +60,10 @@ public :
     static unsigned int GetSeed();
 
     ////////////////////////////////////////////////////////////
-    /// Get a random float number in a given range
+    /// \brief Get a random float number in a given range
     ///
-    /// \return begin : Beginning of the range
+    /// \param begin Beginning of the range
-    /// \return end :   End of the range
+    /// \param end   End of the range
     ///
     /// \return Random number in [begin, end]
     ///
@@ -70,10 +71,10 @@ public :
     static float Random(float begin, float end);
 
     ////////////////////////////////////////////////////////////
-    /// Get a random integer number in a given range
+    /// \brief Get a random integer number in a given range
     ///
-    /// \return begin : Beginning of the range
+    /// \param begin Beginning of the range
-    /// \return end :   End of the range
+    /// \param end   End of the range
     ///
     /// \return Random number in [begin, end]
     ///
@@ -85,3 +86,34 @@ public :
 
 
 #endif // SFML_RANDOMIZER_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Randomizer
+///
+/// sf::Randomizer generates pseudo-random numbers using the
+/// standard library.
+///
+/// Usage example:
+/// \code
+/// int x1 = sf::Randomizer::Random(0, 6);
+/// float x2 = sf::Randomizer::Random(0.f, 1.f);
+/// \endcode
+///
+/// Note that, unlike the standard rand() function, you don't
+/// have to initialize the seed before using this class. SFML does
+/// it for you, so that you will automatically get different results
+/// for every execution of the program.
+///
+/// The SetSeed and GetSeed functions are provided mainly for being
+/// able to reproduce the same set of numbers in a recorded
+/// sequence. This is useful when implementing replays, for example.
+///
+/// The technique used by sf::Randomizer for getting random numbers
+/// is not the most accurate: some numbers may have a slightly higher
+/// probability than others, under certain circumstancies.
+/// This doesn't matter in 99.9% of situations, but if you really
+/// need a generator which is mathematically more robust
+/// you should use another library for that part (see boost.random).
+///
+////////////////////////////////////////////////////////////

include/SFML/System/Resource.hpp

@@ -43,8 +43,9 @@ namespace sf
 template <typename> class ResourcePtr;
 
 ////////////////////////////////////////////////////////////
-/// Base class for every resource that needs to notify
+/// \brief Base class for resources that need to notify
-/// dependent classes about its destruction
+///        dependent classes about their destruction
+///
 ////////////////////////////////////////////////////////////
 template <typename T>
 class Resource
@@ -52,31 +53,31 @@ class Resource
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     Resource();
 
     ////////////////////////////////////////////////////////////
-    /// Copy constructor
+    /// \brief Copy constructor
     ///
-    /// \param copy : Resource to copy
+    /// \param copy Instance to copy
     ///
     ////////////////////////////////////////////////////////////
     Resource(const Resource<T>& copy);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~Resource();
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator
+    /// \brief Assignment operator
     ///
-    /// \param other : Resource to copy
+    /// \param other Instance to copy
     ///
-    /// \return Reference to this
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
     Resource<T>& operator =(const Resource<T>& other);
@@ -86,17 +87,23 @@ private :
     friend class ResourcePtr<T>;
 
     ////////////////////////////////////////////////////////////
-    /// Connect a ResourcePtr to this resource
+    /// \brief Connect a ResourcePtr to this resource
     ///
-    /// \param observer : Observer to add
+    /// A connected ResourcePtr will be notified of the
+    /// destruction of this instance.
+    ///
+    /// \param observer ResourcePtr to connect
     ///
     ////////////////////////////////////////////////////////////
     void Connect(ResourcePtr<T>& observer) const;
 
     ////////////////////////////////////////////////////////////
-    /// Disconnect a ResourcePtr from this resource
+    /// \brief Disconnect a ResourcePtr from this resource
     ///
-    /// \param observer : Observer to remove
+    /// The disconnected ResourcePtr will no longer be notified
+    /// if this instance is destroyed.
+    ///
+    /// \param observer ResourcePtr to disconnect
     ///
     ////////////////////////////////////////////////////////////
     void Disconnect(ResourcePtr<T>& observer) const;
@@ -109,8 +116,8 @@ private :
 
 
 ////////////////////////////////////////////////////////////
-/// Safe pointer to a T resource (inheriting from sf::Resource<T>),
+/// \brief Safe pointer to a sf::Resource<T>
-/// its pointer is automatically reseted when the resource is destroyed
+///
 ////////////////////////////////////////////////////////////
 template <typename T>
 class ResourcePtr
@@ -118,83 +125,98 @@ class ResourcePtr
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// A default constructed ResourcePtr is empty (null).
     ///
     ////////////////////////////////////////////////////////////
     ResourcePtr();
 
     ////////////////////////////////////////////////////////////
-    /// Construct from a raw resource
+    /// \brief Construct from a raw pointer
     ///
-    /// \param resource : Internal resource
+    /// \param resource Raw pointer to the resource to wrap
     ///
     ////////////////////////////////////////////////////////////
     ResourcePtr(const T* resource);
 
     ////////////////////////////////////////////////////////////
-    /// Copy constructor
+    /// \brief Copy constructor
     ///
-    /// \param copy : Instance to copy
+    /// The new ResourcePtr will share the same resource as \a copy.
+    ///
+    /// \param copy Instance to copy
     ///
     ////////////////////////////////////////////////////////////
     ResourcePtr(const ResourcePtr<T>& copy);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~ResourcePtr();
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator from another ResourcePtr
+    /// \brief Assignment operator for a ResourcePtr parameter
     ///
-    /// \param other : Resource pointer to assign
+    /// \param other ResourcePtr to assign
     ///
-    /// \return Reference to this
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
     ResourcePtr<T>& operator =(const ResourcePtr<T>& other);
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator from a raw resource
+    /// \brief Assignment operator for a raw pointer parameter
     ///
-    /// \param resource : Resource to assign
+    /// \param resource Resource to assign
     ///
-    /// \return Reference to this
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
     ResourcePtr<T>& operator =(const T* resource);
 
     ////////////////////////////////////////////////////////////
-    /// Cast operator to implicitely convert the resource pointer to
+    /// \brief Cast operator to implicitely convert the resource
-    /// its raw pointer type.
+    ///        pointer to its raw pointer type (T*)
-    /// This might be dangerous in the general case, but in this context
-    /// it is safe enough to define this operator
     ///
-    /// \return Pointer to the actual resource
+    /// This might be dangerous in the general case, but in this context
+    /// it is safe enough to define this operator.
+    ///
+    /// \return Read-only pointer to the actual resource
     ///
     ////////////////////////////////////////////////////////////
     operator const T*() const;
 
     ////////////////////////////////////////////////////////////
-    /// Operator * overload to return a reference to the actual resource
+    /// \brief Overload of unary operator *
     ///
-    /// \return Reference to the internal resource
+    /// Like raw pointers, applying the * operator returns a
+    /// reference to the pointed object.
+    ///
+    /// \return Reference to the pointed resource
     ///
     ////////////////////////////////////////////////////////////
     const T& operator *() const;
 
     ////////////////////////////////////////////////////////////
-    /// Operator -> overload to return a pointer to the actual resource
+    /// \brief Overload of operator ->
     ///
-    /// \return Pointer to the internal resource
+    /// Like raw pointers, applying the -> operator returns the
+    /// pointed object.
+    ///
+    /// \return Pointed resource
     ///
     ////////////////////////////////////////////////////////////
     const T* operator ->() const;
 
     ////////////////////////////////////////////////////////////
-    /// Function called when the observed resource is about to be
+    /// \brief Function called when the observed resource
-    /// destroyed
+    ///        is about to be destroyed
+    ///
+    /// This functions is called by the destructor of the pointed
+    /// resource. It allows this instance to reset its internal pointer
+    /// when the resource is destroyed, and avoid dangling pointers.
     ///
     ////////////////////////////////////////////////////////////
     void OnResourceDestroyed();
@@ -214,3 +236,47 @@ private :
 
 
 #endif // SFML_RESOURCE_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Resource
+///
+/// sf::Resource is a base for classes that want to be
+/// compatible with the sf::ResourcePtr safe pointer.
+///
+/// See sf::ResourcePtr for a complete explanation.
+///
+/// \see sf::ResourcePtr
+///
+////////////////////////////////////////////////////////////
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::ResourcePtr
+///
+/// sf::ResourcePtr is a special kind of smart pointer for
+/// resources. Its main feature is to automatically
+/// reset its internal pointer to 0 when the resource
+/// gets destroyed, so that pointers to a resource never
+/// become invalid when the resource is destroyed. Instead,
+/// it properly returns 0 when the resource no longer exists.
+///
+/// Its usage is completely transparent, so that it is similar
+/// to manipulating the raw resource directly (like any smart pointer).
+///
+/// For sf::ResourcePtr<T> to work, T must inherit from
+/// the sf::Resource class.
+///
+/// These two classes are heavily used internally in SFML
+/// to safely handle resources and the classes that use them:
+/// \li sf::Image / sf::Sprite
+/// \li sf::Font / sf::String
+/// \li sf::SoundBuffer / sf::Sound
+///
+/// sf::Resource and sf::ResourcePtr are designed for internal use,
+/// but if you feel like they would fit well in your implementation
+/// there's no problem to use them.
+///
+/// \see sf::Resource
+///
+////////////////////////////////////////////////////////////

src/SFML/System/Clock.cpp

@@ -32,16 +32,12 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Clock::Clock()
 {
     Reset();
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the time elapsed since last reset
 ////////////////////////////////////////////////////////////
 float Clock::GetElapsedTime() const
 {
@@ -49,8 +45,6 @@ float Clock::GetElapsedTime() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Restart the timer
 ////////////////////////////////////////////////////////////
 void Clock::Reset()
 {

src/SFML/System/Lock.cpp

@@ -32,8 +32,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Construct the lock with a target mutex (lock it)
-////////////////////////////////////////////////////////////
 Lock::Lock(Mutex& mutex) :
 myMutex(mutex)
 {
@@ -41,8 +39,6 @@ myMutex(mutex)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor (unlocks the mutex)
 ////////////////////////////////////////////////////////////
 Lock::~Lock()
 {

src/SFML/System/Mutex.cpp

@@ -42,16 +42,12 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Mutex::Mutex()
 {
     myMutexImpl = new priv::MutexImpl;
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 Mutex::~Mutex()
 {
@@ -59,8 +55,6 @@ Mutex::~Mutex()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Lock the mutex
 ////////////////////////////////////////////////////////////
 void Mutex::Lock()
 {
@@ -68,8 +62,6 @@ void Mutex::Lock()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Unlock the mutex
 ////////////////////////////////////////////////////////////
 void Mutex::Unlock()
 {

src/SFML/System/Randomizer.cpp

@@ -30,9 +30,13 @@
 #include <cstdlib>
 
 
+////////////////////////////////////////////////////////////
+// Private data
+////////////////////////////////////////////////////////////
 namespace
 {
-    // Set the random numbers sequence seed with the current system time, so that it is always different
+    // Initialize the generator's seed with the current system time
+    // in milliseconds, so that it is always different
     unsigned int InitializeSeed()
     {
         unsigned int seed = static_cast<unsigned int>(sf::priv::Platform::GetSystemTime() * 1000);
@@ -48,9 +52,6 @@ namespace
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Set the seed for the generator. Using a known seed
-/// allows you to reproduce the same sequence of random number
-////////////////////////////////////////////////////////////
 void Randomizer::SetSeed(unsigned int seed)
 {
     srand(seed);
@@ -58,8 +59,6 @@ void Randomizer::SetSeed(unsigned int seed)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the seed used to generate random numbers the generator.
 ////////////////////////////////////////////////////////////
 unsigned int Randomizer::GetSeed()
 {
@@ -67,13 +66,10 @@ unsigned int Randomizer::GetSeed()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a random float number in a given range
 ////////////////////////////////////////////////////////////
 float Randomizer::Random(float begin, float end)
 {
     // This is not the best algorithm, but it is fast and will be enough in most cases
-    // (see Google for best approaches)
 
     return static_cast<float>(rand()) / RAND_MAX * (end - begin) + begin;
 }
@@ -85,7 +81,6 @@ float Randomizer::Random(float begin, float end)
 int Randomizer::Random(int begin, int end)
 {
     // This is not the best algorithm, but it is fast and will be enough in most cases
-    // (see Google for best approaches)
 
     return rand() % (end - begin + 1) + begin;
 }

src/SFML/System/Unix/MutexImpl.cpp

@@ -33,16 +33,12 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 MutexImpl::MutexImpl()
 {
     pthread_mutex_init(&myMutex, NULL);
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 MutexImpl::~MutexImpl()
 {
@@ -50,8 +46,6 @@ MutexImpl::~MutexImpl()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Lock the mutex
 ////////////////////////////////////////////////////////////
 void MutexImpl::Lock()
 {
@@ -59,8 +53,6 @@ void MutexImpl::Lock()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Unlock the mutex
 ////////////////////////////////////////////////////////////
 void MutexImpl::Unlock()
 {

src/SFML/System/Unix/MutexImpl.hpp

@@ -37,32 +37,32 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Unix implementation of mutexes
+/// \brief Unix implementation of mutexes
 ////////////////////////////////////////////////////////////
 class MutexImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     MutexImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~MutexImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Lock the mutex
+    /// \brief Lock the mutex
     ///
     ////////////////////////////////////////////////////////////
     void Lock();
 
     ////////////////////////////////////////////////////////////
-    /// Unlock the mutex
+    /// \brief Unlock the mutex
     ///
     ////////////////////////////////////////////////////////////
     void Unlock();

src/SFML/System/Unix/Platform.cpp

@@ -34,8 +34,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Get the current system time
-////////////////////////////////////////////////////////////
 double Platform::GetSystemTime()
 {
     timeval time = {0, 0};
@@ -45,8 +43,6 @@ double Platform::GetSystemTime()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Suspend the execution of the current thread for a specified time
 ////////////////////////////////////////////////////////////
 void Platform::Sleep(float time)
 {

src/SFML/System/Unix/Platform.hpp

@@ -37,15 +37,14 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Unix implementation fo Platform 
+/// \brief Give access to some system-specific low-level functions
-/// Give access to various global system functions
 ////////////////////////////////////////////////////////////
 class Platform
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Get the current system time
+    /// \brief Get the current system time
     ///
     /// \return System time, in seconds
     ///
@@ -53,9 +52,9 @@ public :
     static double GetSystemTime();
 
     ////////////////////////////////////////////////////////////
-    /// Suspend the execution of the current thread for a specified time
+    /// \brief Suspend the execution of the current thread for a specified time
     ///
-    /// \param time : Time to sleep, in seconds
+    /// \param time Time to sleep, in seconds
     ///
     ////////////////////////////////////////////////////////////
     static void Sleep(float time);

src/SFML/System/Unix/ThreadImpl.cpp

@@ -35,8 +35,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 ThreadImpl::ThreadImpl(Thread* owner) :
 myIsActive(true)
 {
@@ -47,8 +45,6 @@ myIsActive(true)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait until the thread finishes
 ////////////////////////////////////////////////////////////
 void ThreadImpl::Wait()
 {
@@ -57,11 +53,6 @@ void ThreadImpl::Wait()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Terminate the thread
-/// Terminating a thread with this function is not safe,
-/// you should rather try to make the thread function
-/// terminate by itself
 ////////////////////////////////////////////////////////////
 void ThreadImpl::Terminate()
 {
@@ -70,8 +61,6 @@ void ThreadImpl::Terminate()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Global entry point for all threads
 ////////////////////////////////////////////////////////////
 void* ThreadImpl::EntryPoint(void* userData)
 {

src/SFML/System/Unix/ThreadImpl.hpp

@@ -39,31 +39,28 @@ class Thread;
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Unix implementation of threads
+/// \brief Unix implementation of threads
 ////////////////////////////////////////////////////////////
 class ThreadImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor, launch the thread
+    /// \brief Default constructor, launch the thread
     ///
-    /// \param owner : Owner Thread instance to run
+    /// \param owner The Thread instance to run
     ///
     ////////////////////////////////////////////////////////////
     ThreadImpl(Thread* owner);
 
     ////////////////////////////////////////////////////////////
-    /// Wait until the thread finishes
+    /// \brief Wait until the thread finishes
     ///
     ////////////////////////////////////////////////////////////
     void Wait();
 
     ////////////////////////////////////////////////////////////
-    /// Terminate the thread
+    /// \brief Terminate the thread
-    /// Terminating a thread with this function is not safe,
-    /// you should rather try to make the thread function
-    /// terminate by itself
     ///
     ////////////////////////////////////////////////////////////
     void Terminate();
@@ -71,11 +68,11 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Global entry point for all threads
+    /// \brief Global entry point for all threads
     ///
-    /// \param userData : User-defined data (contains the Thread instance)
+    /// \param userData User-defined data (contains the Thread instance)
     ///
-    /// \return Error code
+    /// \return Os specific error code
     ///
     ////////////////////////////////////////////////////////////
     static void* EntryPoint(void* userData);

src/SFML/System/Unix/ThreadLocalImpl.cpp

@@ -33,16 +33,12 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor -- allocate the storage
-////////////////////////////////////////////////////////////
 ThreadLocalImpl::ThreadLocalImpl()
 {
     pthread_key_create(&myKey, NULL);
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor -- free the storage
 ////////////////////////////////////////////////////////////
 ThreadLocalImpl::~ThreadLocalImpl()
 {
@@ -50,8 +46,6 @@ ThreadLocalImpl::~ThreadLocalImpl()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void ThreadLocalImpl::SetValue(void* value)
 {
@@ -59,8 +53,6 @@ void ThreadLocalImpl::SetValue(void* value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Retrieve the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void* ThreadLocalImpl::GetValue() const
 {

src/SFML/System/Unix/ThreadLocalImpl.hpp

@@ -37,34 +37,34 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Unix implementation of thread-local storage
+/// \brief Unix implementation of thread-local storage
 ////////////////////////////////////////////////////////////
 class ThreadLocalImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor -- allocate the storage
+    /// \brief Default constructor -- allocate the storage
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocalImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor -- free the storage
+    /// \brief Destructor -- free the storage
     ///
     ////////////////////////////////////////////////////////////
     ~ThreadLocalImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Set the thread-specific value of the variable
+    /// \brief Set the thread-specific value of the variable
     ///
-    /// \param value : Value of the variable for this thread
+    /// \param value Value of the variable for this thread
     ///
     ////////////////////////////////////////////////////////////
     void SetValue(void* value);
 
     ////////////////////////////////////////////////////////////
-    /// Retrieve the thread-specific value of the variable
+    /// \brief Retrieve the thread-specific value of the variable
     ///
     /// \return Value of the variable for this thread
     ///

src/SFML/System/Win32/MutexImpl.cpp

@@ -33,16 +33,12 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 MutexImpl::MutexImpl()
 {
     InitializeCriticalSection(&myMutex);
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 MutexImpl::~MutexImpl()
 {
@@ -50,8 +46,6 @@ MutexImpl::~MutexImpl()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Lock the mutex
 ////////////////////////////////////////////////////////////
 void MutexImpl::Lock()
 {
@@ -59,8 +53,6 @@ void MutexImpl::Lock()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Unlock the mutex
 ////////////////////////////////////////////////////////////
 void MutexImpl::Unlock()
 {

src/SFML/System/Win32/MutexImpl.hpp

@@ -37,32 +37,32 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Windows implementation of mutexes
+/// \brief Windows implementation of mutexes
 ////////////////////////////////////////////////////////////
 class MutexImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     MutexImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~MutexImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Lock the mutex
+    /// \brief Lock the mutex
     ///
     ////////////////////////////////////////////////////////////
     void Lock();
 
     ////////////////////////////////////////////////////////////
-    /// Unlock the mutex
+    /// \brief Unlock the mutex
     ///
     ////////////////////////////////////////////////////////////
     void Unlock();

src/SFML/System/Win32/Platform.cpp

@@ -34,8 +34,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Get the current system time
-////////////////////////////////////////////////////////////
 double Platform::GetSystemTime()
 {
     static LARGE_INTEGER Frequency;
@@ -57,8 +55,6 @@ double Platform::GetSystemTime()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Suspend the execution of the current thread for a specified time
 ////////////////////////////////////////////////////////////
 void Platform::Sleep(float Time)
 {

src/SFML/System/Win32/Platform.hpp

@@ -37,15 +37,15 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Win32 implementation of Platform.
+/// \brief Gives access to some system-specific low-level functions
-/// Gives access to various global system functions
+///
 ////////////////////////////////////////////////////////////
 class Platform
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Get the current system time
+    /// \brief Get the current system time
     ///
     /// \return System time, in seconds
     ///
@@ -53,9 +53,9 @@ public :
     static double GetSystemTime();
 
     ////////////////////////////////////////////////////////////
-    /// Suspend the execution of the current thread for a specified time
+    /// \brief Suspend the execution of the current thread for a specified time
     ///
-    /// \param time : Time to sleep, in seconds
+    /// \param time Time to sleep, in seconds
     ///
     ////////////////////////////////////////////////////////////
     static void Sleep(float time);

src/SFML/System/Win32/ThreadImpl.cpp

@@ -36,8 +36,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 ThreadImpl::ThreadImpl(Thread* owner)
 {
     myThread = reinterpret_cast<HANDLE>(_beginthreadex(NULL, 0, &ThreadImpl::EntryPoint, owner, 0, NULL));
@@ -47,8 +45,6 @@ ThreadImpl::ThreadImpl(Thread* owner)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 ThreadImpl::~ThreadImpl()
 {
@@ -57,8 +53,6 @@ ThreadImpl::~ThreadImpl()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait until the thread finishes
 ////////////////////////////////////////////////////////////
 void ThreadImpl::Wait()
 {
@@ -67,11 +61,6 @@ void ThreadImpl::Wait()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Terminate the thread
-/// Terminating a thread with this function is not safe,
-/// you should rather try to make the thread function
-/// terminate by itself
 ////////////////////////////////////////////////////////////
 void ThreadImpl::Terminate()
 {
@@ -80,8 +69,6 @@ void ThreadImpl::Terminate()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Global entry point for all threads
 ////////////////////////////////////////////////////////////
 unsigned int __stdcall ThreadImpl::EntryPoint(void* userData)
 {

src/SFML/System/Win32/ThreadImpl.hpp

@@ -39,37 +39,34 @@ class Thread;
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Windows implementation of threads
+/// \brief Windows implementation of threads
 ////////////////////////////////////////////////////////////
 class ThreadImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor, launch the thread
+    /// \brief Default constructor, launch the thread
     ///
-    /// \param owner : Owner Thread instance to run
+    /// \param owner The Thread instance to run
     ///
     ////////////////////////////////////////////////////////////
     ThreadImpl(Thread* owner);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~ThreadImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Wait until the thread finishes
+    /// \brief Wait until the thread finishes
     ///
     ////////////////////////////////////////////////////////////
     void Wait();
 
     ////////////////////////////////////////////////////////////
-    /// Terminate the thread
+    /// \brief Terminate the thread
-    /// Terminating a thread with this function is not safe,
-    /// you should rather try to make the thread function
-    /// terminate by itself
     ///
     ////////////////////////////////////////////////////////////
     void Terminate();
@@ -77,11 +74,11 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Global entry point for all threads
+    /// \brief Global entry point for all threads
     ///
-    /// \param userData : User-defined data (contains the Thread instance)
+    /// \param userData User-defined data (contains the Thread instance)
     ///
-    /// \return Error code
+    /// \return OS specific error code
     ///
     ////////////////////////////////////////////////////////////
     static unsigned int __stdcall EntryPoint(void* userData);

src/SFML/System/Win32/ThreadLocalImpl.cpp

@@ -33,16 +33,12 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor -- allocate the storage
-////////////////////////////////////////////////////////////
 ThreadLocalImpl::ThreadLocalImpl()
 {
     myIndex = TlsAlloc();
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor -- free the storage
 ////////////////////////////////////////////////////////////
 ThreadLocalImpl::~ThreadLocalImpl()
 {
@@ -50,8 +46,6 @@ ThreadLocalImpl::~ThreadLocalImpl()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void ThreadLocalImpl::SetValue(void* value)
 {
@@ -59,8 +53,6 @@ void ThreadLocalImpl::SetValue(void* value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Retrieve the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void* ThreadLocalImpl::GetValue() const
 {

src/SFML/System/Win32/ThreadLocalImpl.hpp

@@ -37,34 +37,34 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Windows implementation of thread-local storage
+/// \brief Windows implementation of thread-local storage
 ////////////////////////////////////////////////////////////
 class ThreadLocalImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor -- allocate the storage
+    /// \brief Default constructor -- allocate the storage
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocalImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor -- free the storage
+    /// \brief Destructor -- free the storage
     ///
     ////////////////////////////////////////////////////////////
     ~ThreadLocalImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Set the thread-specific value of the variable
+    /// \brief Set the thread-specific value of the variable
     ///
-    /// \param value : Value of the variable for this thread
+    /// \param value Value of the variable for this thread
     ///
     ////////////////////////////////////////////////////////////
     void SetValue(void* value);
 
     ////////////////////////////////////////////////////////////
-    /// Retrieve the thread-specific value of the variable
+    /// \brief Retrieve the thread-specific value of the variable
     ///
     /// \return Value of the variable for this thread
     ///