Improved documentation of more classes in the system module

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

include/SFML/System/Randomizer.hpp

@@ -35,6 +35,7 @@ namespace sf
 {
 ////////////////////////////////////////////////////////////
 /// \brief Utility class for generating pseudo-random numbers
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Randomizer
 {

include/SFML/System/Resource.inl

@@ -23,8 +23,6 @@
 ////////////////////////////////////////////////////////////
 
 
-////////////////////////////////////////////////////////////
-/// Default constructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 Resource<T>::Resource()
@@ -33,8 +31,6 @@ Resource<T>::Resource()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy constructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 Resource<T>::Resource(const Resource<T>&)
@@ -43,8 +39,6 @@ Resource<T>::Resource(const Resource<T>&)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 Resource<T>::~Resource()
@@ -57,8 +51,6 @@ Resource<T>::~Resource()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
 ////////////////////////////////////////////////////////////
 template <typename T>
 Resource<T>& Resource<T>::operator =(const Resource<T>&)
@@ -68,8 +60,6 @@ Resource<T>& Resource<T>::operator =(const Resource<T>&)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Connect a ResourcePtr to this resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 void Resource<T>::Connect(ResourcePtr<T>& observer) const
@@ -78,8 +68,6 @@ void Resource<T>::Connect(ResourcePtr<T>& observer) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Disconnect a ResourcePtr from this resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 void Resource<T>::Disconnect(ResourcePtr<T>& observer) const

include/SFML/System/ResourcePtr.inl

@@ -23,8 +23,6 @@
 ////////////////////////////////////////////////////////////
 
 
-////////////////////////////////////////////////////////////
-/// Default constructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>::ResourcePtr() :
@@ -34,8 +32,6 @@ myResource(NULL)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct from a raw resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>::ResourcePtr(const T* resource) :
@@ -46,8 +42,6 @@ myResource(resource)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy constructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>::ResourcePtr(const ResourcePtr<T>& copy) :
@@ -58,8 +52,6 @@ myResource(copy.myResource)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>::~ResourcePtr()
@@ -69,8 +61,6 @@ ResourcePtr<T>::~ResourcePtr()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator from another ResourcePtr
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>& ResourcePtr<T>::operator =(const ResourcePtr<T>& other)
@@ -87,8 +77,6 @@ ResourcePtr<T>& ResourcePtr<T>::operator =(const ResourcePtr<T>& other)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator from a raw resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>& ResourcePtr<T>::operator =(const T* resource)
@@ -105,11 +93,6 @@ ResourcePtr<T>& ResourcePtr<T>::operator =(const T* resource)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Cast operator to implicitely convert the resource pointer to
-/// its raw pointer type.
-/// This might be dangerous in the general case, but in this context
-/// it is safe enough to define this operator
 ////////////////////////////////////////////////////////////
 template <typename T>
 ResourcePtr<T>::operator const T*() const
@@ -118,8 +101,6 @@ ResourcePtr<T>::operator const T*() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Operator * overload to return a reference to the actual resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 const T& ResourcePtr<T>::operator *() const
@@ -128,8 +109,6 @@ const T& ResourcePtr<T>::operator *() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Operator -> overload to return a pointer to the actual resource
 ////////////////////////////////////////////////////////////
 template <typename T>
 const T* ResourcePtr<T>::operator ->() const
@@ -138,9 +117,6 @@ const T* ResourcePtr<T>::operator ->() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Function called when the observed resource is about to be
-/// destroyed
 ////////////////////////////////////////////////////////////
 template <typename T>
 void ResourcePtr<T>::OnResourceDestroyed()

include/SFML/System/Sleep.hpp

@@ -34,9 +34,12 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Make the current thread sleep for a given time
+/// \brief Make the current thread sleep for a given time
 ///
-/// \param duration : Time to sleep, in seconds (must be >= 0)
+/// sf::Sleep 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 seconds (must be positive)
 ///
 ////////////////////////////////////////////////////////////
 void SFML_API Sleep(float duration);

include/SFML/System/Thread.hpp

@@ -41,11 +41,7 @@ namespace priv
 }
 
 ////////////////////////////////////////////////////////////
-/// Thread defines an easy way to manipulate a thread.
+/// \brief Utility class to manipulate threads
-/// There are two ways to use Thread :
-/// - Inherit from it and override the Run() virtual function
-/// - Construct a Thread instance and pass it a function
-/// pointer to call
 ////////////////////////////////////////////////////////////
 class SFML_API Thread : NonCopyable
 {
@@ -54,37 +50,47 @@ public :
     typedef void (*FuncType)(void*);
 
     ////////////////////////////////////////////////////////////
-    /// Construct the thread from a function pointer
+    /// \brief Construct the thread from a function pointer
     ///
-    /// \param function : Entry point of the thread
+    /// \param function Entry point of the thread
-    /// \param userData : Data to pass to the thread function (NULL by default)
+    /// \param userData Data to pass to the thread function (NULL by default)
     ///
     ////////////////////////////////////////////////////////////
     Thread(FuncType function, void* userData = NULL);
 
     ////////////////////////////////////////////////////////////
-    /// Virtual destructor
+    /// \brief Virtual destructor
+    ///
+    /// This destructor calls Wait(), so that the thread cannot
+    /// survive when its sf::Thread instance is destroyed.
     ///
     ////////////////////////////////////////////////////////////
     virtual ~Thread();
 
     ////////////////////////////////////////////////////////////
-    /// Create and run the thread
+    /// \brief Run the thread
     ///
     ////////////////////////////////////////////////////////////
     void Launch();
 
     ////////////////////////////////////////////////////////////
-    /// Wait until the thread finishes
+    /// \brief Wait until the thread finishes
+    ///
+    /// This function will block the execution until the
+    /// thread's function ends.
     ///
     ////////////////////////////////////////////////////////////
     void Wait();
 
     ////////////////////////////////////////////////////////////
-    /// Terminate the thread
+    /// \brief Terminate the thread
+    ///
+    /// This function immediately stops the thread, without waiting
+    /// for its function to finish.
     /// Terminating a thread with this function is not safe,
-    /// you should rather try to make the thread function
+    /// and can lead to local variables not being destroyed
-    /// terminate by itself
+    /// on some operating systems. You should rather try to make
+    /// the thread function terminate by itself.
     ///
     ////////////////////////////////////////////////////////////
     void Terminate();
@@ -92,7 +98,9 @@ public :
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// This constructor is only accessible from derived classes
     ///
     ////////////////////////////////////////////////////////////
     Thread();
@@ -102,7 +110,10 @@ private :
     friend class priv::ThreadImpl;
 
     ////////////////////////////////////////////////////////////
-    /// Function called as the thread entry point
+    /// \brief Function called as the entry point of the thread
+    ///
+    /// You must override this function when inheriting from
+    /// sf::Thread.
     ///
     ////////////////////////////////////////////////////////////
     virtual void Run();
@@ -119,3 +130,68 @@ private :
 
 
 #endif // SFML_THREAD_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Thread
+///
+/// Threads provide a way to run multiple parts of the code
+/// in parallel. When you launch a new thread, the execution
+/// is split and both the new thread and the caller run
+/// in parallel.
+///
+/// There are two ways to use sf::Thread. The first (and
+/// preferred) way of using it is to created derived classes.
+/// When inheriting from sf::Thread, the virtual function
+/// Run() has to be overriden, and defines the entry point
+/// of the thread. The thread automatically stops when
+/// this function ends.
+///
+/// Usage example:
+/// \code
+/// class MyThread : public sf::Thread
+/// {
+/// private :
+/// 
+///     virtual void Run()
+///     {
+///         // beginning of the thread
+///         ...
+///         // end of the thread
+///     }
+/// };
+///
+/// MyThread mythread;
+/// mythread.Launch(); // start the thread (internally calls thread.Run())
+///
+/// // from now on, both mythread and the main thread run in parallel
+/// \endcode
+///
+/// The second way of using sf::Thread uses a non-member function
+/// as the entry point and thus doesn't involve creating
+/// a new class. However, this method is only provided for
+/// compatibility with C-style code or for fast prototyping;
+/// you are strongly encouraged to use the first method.
+///
+/// Usage example:
+/// \code
+/// void ThreadFunc(void* data)
+/// {
+///     // beginning of the thread
+///     ...
+///     // end of the thread
+/// }
+///
+/// sf::Thread mythread(&ThreadFunc, NULL);
+/// mythread.Launch(); // start the thread (internally calls ThreadFunc(NULL))
+///
+/// // from now on, both mythread and the main thread run in parallel
+/// \endcode
+///
+/// Creating parallel threads of execution can be dangerous:
+/// all threads inside the same process share the same memory space,
+/// which means that you may end up accessing the same variable
+/// from multiple threads at the same time. To prevent this
+/// kind of situations, you can use mutexes (see sf::Mutex).
+///
+////////////////////////////////////////////////////////////

include/SFML/System/ThreadLocal.hpp

@@ -41,42 +41,39 @@ namespace priv
 }
 
 ////////////////////////////////////////////////////////////
-/// Wrapper to handle variables that are local to threads.
+/// \brief Defines variables with thread-local storage
-/// This means that the same ThreadLocalStorage variable will
+///
-/// hold a different value for each different thread.
-/// For a more strongly-typed interface, use the ThreadLocal
-/// template class.
 ////////////////////////////////////////////////////////////
 class SFML_API ThreadLocal : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
-    /// \param value : Optional value to initalize the variable (NULL by default)
+    /// \param value Optional value to initalize the variable (NULL by default)
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocal(void* value = NULL);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~ThreadLocal();
 
     ////////////////////////////////////////////////////////////
-    /// 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 the current 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
+    /// \return Value of the variable for the current thread
     ///
     ////////////////////////////////////////////////////////////
     void* GetValue() const;
@@ -93,3 +90,13 @@ private :
 
 
 #endif // SFML_THREADLOCAL_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::ThreadLocal
+///
+/// This class manipulates void* parameters and thus is not
+/// appropriate for strongly-typed variables. You should rather
+/// use the sf::ThreadLocalPtr template class.
+///
+////////////////////////////////////////////////////////////

include/SFML/System/ThreadLocalPtr.hpp

@@ -34,7 +34,8 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Type-safe wrapper for thread local pointer variables
+/// \brief Pointer to a thread-local variable
+///
 ////////////////////////////////////////////////////////////
 template <typename T>
 class ThreadLocalPtr : private ThreadLocal
@@ -42,53 +43,60 @@ class ThreadLocalPtr : private ThreadLocal
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
-    /// \param value : Optional value to initalize the variable (NULL by default)
+    /// \param value Optional value to initalize the variable (NULL by default)
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocalPtr(T* value = NULL);
 
     ////////////////////////////////////////////////////////////
-    /// Operator * overload to return a reference to the variable
+    /// \brief Overload of unary operator *
     ///
-    /// \return Reference to the thread-local value of the variable
+    /// Like raw pointers, applying the * operator returns a
+    /// reference to the pointed object.
+    ///
+    /// \return Reference to the pointed object
     ///
     ////////////////////////////////////////////////////////////
     T& operator *() const;
 
     ////////////////////////////////////////////////////////////
-    /// Operator -> overload to return a pointer to the variable
+    /// \brief Overload of operator ->
     ///
-    /// \return Pointer to the thread-local value of the variable
+    /// Like raw pointers, applying the -> operator returns the
+    /// pointed object.
+    ///
+    /// \return Pointed object
     ///
     ////////////////////////////////////////////////////////////
     T* operator ->() const;
 
     ////////////////////////////////////////////////////////////
-    /// Implicit cast operator to T*
+    /// \brief Cast operator to implicitely convert the
+    ///        pointer to its raw pointer type (T*)
     ///
-    /// \return Value of the pointer for this thread
+    /// \return Pointer to the actual object
     ///
     ////////////////////////////////////////////////////////////
     operator T*() const;
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator
+    /// \brief Assignment operator for a raw pointer parameter
     ///
-    /// \param value : New pointer value to assign for this thread
+    /// \param resource Pointer to assign
     ///
-    /// \return Reference to this
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocalPtr<T>& operator =(T* value);
 
     ////////////////////////////////////////////////////////////
-    /// Assignment operator
+    /// \brief Assignment operator for a ThreadLocalPtr parameter
     ///
-    /// \param other : Other thread-local pointer value to assign
+    /// \param other ThreadLocalPtr to assign
     ///
-    /// \return Reference to this
+    /// \return Reference to self
     ///
     ////////////////////////////////////////////////////////////
     ThreadLocalPtr<T>& operator =(const ThreadLocalPtr<T>& other);
@@ -100,3 +108,50 @@ public :
 
 
 #endif // SFML_THREADLOCALPTR_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::ThreadLocalPtr
+///
+/// sf::ThreadLocalPtr is a type-safe wrapper for storing
+/// pointers to thread-local variables. A thread-local
+/// variable holds a different value for each different
+/// thread, unlike normal variable that are shared.
+///
+/// Its usage is completely transparent, so that it is similar
+/// to manipulating the raw pointer directly (like any smart pointer).
+///
+/// Usage example:
+/// \code
+/// MyClass object1;
+/// MyClass object2;
+/// sf::ThreadLocalPtr<MyClass> objectPtr;
+///
+/// void Thread1(void*)
+/// {
+///     objectPtr = &object1; // doesn't impact Thread2
+///     ...
+/// }
+///
+/// void Thread1(void*)
+/// {
+///     objectPtr = &object2; // doesn't impact Thread1
+///     ...
+/// }
+///
+/// int main()
+/// {
+///     // Create and launch the two threads
+///     sf::Thread thread1(&Thread1);
+///     sf::Thread thread2(&Thread2);
+///     thread1.Launch();
+///     thread2.Launch();
+///
+///     return 0;
+/// }
+/// \endcode
+///
+/// ThreadLocalPtr is designed for internal use; however you
+/// can use it if you feel like it fits well your implementation.
+///
+////////////////////////////////////////////////////////////

include/SFML/System/ThreadLocalPtr.inl

@@ -26,8 +26,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 template <typename T>
 ThreadLocalPtr<T>::ThreadLocalPtr(T* Value) :
 ThreadLocal(Value)
@@ -35,8 +33,6 @@ ThreadLocal(Value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Operator * overload to return a reference to the variable
 ////////////////////////////////////////////////////////////
 template <typename T>
 T& ThreadLocalPtr<T>::operator *() const
@@ -45,8 +41,6 @@ T& ThreadLocalPtr<T>::operator *() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Operator -> overload to return a pointer to the variable
 ////////////////////////////////////////////////////////////
 template <typename T>
 T* ThreadLocalPtr<T>::operator ->() const
@@ -55,8 +49,6 @@ T* ThreadLocalPtr<T>::operator ->() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Implicit cast operator to T*
 ////////////////////////////////////////////////////////////
 template <typename T>
 ThreadLocalPtr<T>::operator T*() const
@@ -65,8 +57,6 @@ ThreadLocalPtr<T>::operator T*() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
 ////////////////////////////////////////////////////////////
 template <typename T>
 ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(T* Value)
@@ -76,8 +66,6 @@ ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(T* Value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
 ////////////////////////////////////////////////////////////
 template <typename T>
 ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(const ThreadLocalPtr<T>& Other)

src/SFML/System/Sleep.cpp

@@ -32,8 +32,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Make the current thread sleep for a given time
-////////////////////////////////////////////////////////////
 void Sleep(float duration)
 {
     if (duration >= 0)

src/SFML/System/Thread.cpp

@@ -42,8 +42,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Thread::Thread() :
 myThreadImpl(NULL),
 myFunction  (NULL),
@@ -53,8 +51,6 @@ myUserData  (NULL)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the thread from a function pointer
 ////////////////////////////////////////////////////////////
 Thread::Thread(Thread::FuncType function, void* userData) :
 myThreadImpl(NULL),
@@ -65,8 +61,6 @@ myUserData  (userData)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Virtual destructor
 ////////////////////////////////////////////////////////////
 Thread::~Thread()
 {
@@ -74,8 +68,6 @@ Thread::~Thread()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create and run the thread
 ////////////////////////////////////////////////////////////
 void Thread::Launch()
 {
@@ -84,8 +76,6 @@ void Thread::Launch()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Wait until the thread finishes
 ////////////////////////////////////////////////////////////
 void Thread::Wait()
 {
@@ -98,11 +88,6 @@ void Thread::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 Thread::Terminate()
 {
@@ -115,8 +100,6 @@ void Thread::Terminate()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Function called as the thread entry point
 ////////////////////////////////////////////////////////////
 void Thread::Run()
 {

src/SFML/System/ThreadLocal.cpp

@@ -42,8 +42,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 ThreadLocal::ThreadLocal(void* value)
 {
     myImpl = new priv::ThreadLocalImpl;
@@ -51,8 +49,6 @@ ThreadLocal::ThreadLocal(void* value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 ThreadLocal::~ThreadLocal()
 {
@@ -60,8 +56,6 @@ ThreadLocal::~ThreadLocal()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void ThreadLocal::SetValue(void* value)
 {
@@ -69,8 +63,6 @@ void ThreadLocal::SetValue(void* value)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Retrieve the thread-specific value of the variable
 ////////////////////////////////////////////////////////////
 void* ThreadLocal::GetValue() const
 {