From 351a43f69681f38b1a21b47684e3e69e48471120 Mon Sep 17 00:00:00 2001 From: LaurentGom Date: Fri, 14 Aug 2009 20:00:42 +0000 Subject: [PATCH] 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 | 37 +++++- include/SFML/System/Lock.hpp | 75 +++++++++++- include/SFML/System/Mutex.hpp | 65 ++++++++-- include/SFML/System/NonCopyable.hpp | 60 +++++++-- include/SFML/System/Randomizer.hpp | 56 +++++++-- include/SFML/System/Resource.hpp | 142 ++++++++++++++++------ src/SFML/System/Clock.cpp | 6 - src/SFML/System/Lock.cpp | 4 - src/SFML/System/Mutex.cpp | 8 -- src/SFML/System/Randomizer.cpp | 15 +-- src/SFML/System/Unix/MutexImpl.cpp | 8 -- src/SFML/System/Unix/MutexImpl.hpp | 10 +- src/SFML/System/Unix/Platform.cpp | 4 - src/SFML/System/Unix/Platform.hpp | 9 +- src/SFML/System/Unix/ThreadImpl.cpp | 11 -- src/SFML/System/Unix/ThreadImpl.hpp | 19 ++- src/SFML/System/Unix/ThreadLocalImpl.cpp | 8 -- src/SFML/System/Unix/ThreadLocalImpl.hpp | 12 +- src/SFML/System/Win32/MutexImpl.cpp | 8 -- src/SFML/System/Win32/MutexImpl.hpp | 10 +- src/SFML/System/Win32/Platform.cpp | 4 - src/SFML/System/Win32/Platform.hpp | 10 +- src/SFML/System/Win32/ThreadImpl.cpp | 13 -- src/SFML/System/Win32/ThreadImpl.hpp | 21 ++-- src/SFML/System/Win32/ThreadLocalImpl.cpp | 8 -- src/SFML/System/Win32/ThreadLocalImpl.hpp | 12 +- 26 files changed, 414 insertions(+), 221 deletions(-) diff --git a/include/SFML/System/Clock.hpp b/include/SFML/System/Clock.hpp index 76c00550..6fb6b845 100644 --- a/include/SFML/System/Clock.hpp +++ b/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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Lock.hpp b/include/SFML/System/Lock.hpp index cca38f56..978bd35c 100644 --- a/include/SFML/System/Lock.hpp +++ b/include/SFML/System/Lock.hpp @@ -36,23 +36,27 @@ namespace sf class Mutex; //////////////////////////////////////////////////////////// -/// Lock is an exception-safe automatic wrapper for -/// locking and unlocking mutexes +/// \brief Automatic wrapper for 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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Mutex.hpp b/include/SFML/System/Mutex.hpp index 1e267084..9c9848a8 100644 --- a/include/SFML/System/Mutex.hpp +++ b/include/SFML/System/Mutex.hpp @@ -40,35 +40,38 @@ namespace priv } //////////////////////////////////////////////////////////// -/// Mutex defines a mutex (MUTual EXclusion) object, -/// that allows a thread to lock critical instructions -/// to avoid simultaneous access with other threads. -/// See Lock for an efficient way of using it. +/// \brief Blocks concurrent access to shared resources +/// from multiple threads +/// //////////////////////////////////////////////////////////// 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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/NonCopyable.hpp b/include/SFML/System/NonCopyable.hpp index 3ac6719f..3081bc62 100644 --- a/include/SFML/System/NonCopyable.hpp +++ b/include/SFML/System/NonCopyable.hpp @@ -34,15 +34,20 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Utility base class to easily declare non-copyable classes. -/// Just inherit from NonCopyable to get a non-copyable class +/// \brief Utility class that makes any derived +/// 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 - /// it to prevent from calling it + /// \brief Disabled copy constructor + /// + /// 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 - /// it to prevent from calling it + /// \brief Disabled assignment operator + /// + /// 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. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Randomizer.hpp b/include/SFML/System/Randomizer.hpp index 1bcdeba5..34f22b42 100644 --- a/include/SFML/System/Randomizer.hpp +++ b/include/SFML/System/Randomizer.hpp @@ -34,24 +34,25 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Randomizer is an utility class for generating pseudo-random -/// numbers +/// \brief Utility class for generating pseudo-random numbers //////////////////////////////////////////////////////////// class SFML_API Randomizer { public : //////////////////////////////////////////////////////////// - /// Set the seed for the generator. Using a known seed - /// allows you to reproduce the same sequence of random number + /// \brief Set a new seed for the generator /// - /// \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 - /// \return end : End of the range + /// \param begin Beginning 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 - /// \return end : End of the range + /// \param begin Beginning 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). +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Resource.hpp b/include/SFML/System/Resource.hpp index bef0c6be..b7d165e7 100644 --- a/include/SFML/System/Resource.hpp +++ b/include/SFML/System/Resource.hpp @@ -43,8 +43,9 @@ namespace sf template class ResourcePtr; //////////////////////////////////////////////////////////// -/// Base class for every resource that needs to notify -/// dependent classes about its destruction +/// \brief Base class for resources that need to notify +/// dependent classes about their destruction +/// //////////////////////////////////////////////////////////// template 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& 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& operator =(const Resource& other); @@ -86,17 +87,23 @@ private : friend class ResourcePtr; //////////////////////////////////////////////////////////// - /// 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& 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& observer) const; @@ -109,8 +116,8 @@ private : //////////////////////////////////////////////////////////// -/// Safe pointer to a T resource (inheriting from sf::Resource), -/// its pointer is automatically reseted when the resource is destroyed +/// \brief Safe pointer to a sf::Resource +/// //////////////////////////////////////////////////////////// template 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& 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& operator =(const ResourcePtr& 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& 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 + /// \brief Cast operator to implicitely convert the resource + /// pointer to its raw pointer type (T*) /// - /// \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 - /// destroyed + /// \brief Function called when the observed resource + /// 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 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 +/// +//////////////////////////////////////////////////////////// diff --git a/src/SFML/System/Clock.cpp b/src/SFML/System/Clock.cpp index 65e0e4d5..baeb9655 100644 --- a/src/SFML/System/Clock.cpp +++ b/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() { diff --git a/src/SFML/System/Lock.cpp b/src/SFML/System/Lock.cpp index 15b435a7..e3a4970c 100644 --- a/src/SFML/System/Lock.cpp +++ b/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() { diff --git a/src/SFML/System/Mutex.cpp b/src/SFML/System/Mutex.cpp index 8d4b49c9..fa542500 100644 --- a/src/SFML/System/Mutex.cpp +++ b/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() { diff --git a/src/SFML/System/Randomizer.cpp b/src/SFML/System/Randomizer.cpp index dc5ba132..e8402436 100644 --- a/src/SFML/System/Randomizer.cpp +++ b/src/SFML/System/Randomizer.cpp @@ -30,9 +30,13 @@ #include +//////////////////////////////////////////////////////////// +// 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(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(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; } diff --git a/src/SFML/System/Unix/MutexImpl.cpp b/src/SFML/System/Unix/MutexImpl.cpp index cb0f7f7b..1da606d9 100644 --- a/src/SFML/System/Unix/MutexImpl.cpp +++ b/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() { diff --git a/src/SFML/System/Unix/MutexImpl.hpp b/src/SFML/System/Unix/MutexImpl.hpp index ed4b1a8d..e6cb5873 100644 --- a/src/SFML/System/Unix/MutexImpl.hpp +++ b/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(); diff --git a/src/SFML/System/Unix/Platform.cpp b/src/SFML/System/Unix/Platform.cpp index 1f4fb1c7..8446c1bb 100644 --- a/src/SFML/System/Unix/Platform.cpp +++ b/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) { diff --git a/src/SFML/System/Unix/Platform.hpp b/src/SFML/System/Unix/Platform.hpp index b994dd09..0173e64b 100644 --- a/src/SFML/System/Unix/Platform.hpp +++ b/src/SFML/System/Unix/Platform.hpp @@ -37,15 +37,14 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// Unix implementation fo Platform -/// Give access to various global system functions +/// \brief Give access to some system-specific low-level 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); diff --git a/src/SFML/System/Unix/ThreadImpl.cpp b/src/SFML/System/Unix/ThreadImpl.cpp index 2d7e1db4..0b4b1a24 100644 --- a/src/SFML/System/Unix/ThreadImpl.cpp +++ b/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) { diff --git a/src/SFML/System/Unix/ThreadImpl.hpp b/src/SFML/System/Unix/ThreadImpl.hpp index 90e67718..f059ca6f 100644 --- a/src/SFML/System/Unix/ThreadImpl.hpp +++ b/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 - /// Terminating a thread with this function is not safe, - /// you should rather try to make the thread function - /// terminate by itself + /// \brief Terminate the thread /// //////////////////////////////////////////////////////////// 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); diff --git a/src/SFML/System/Unix/ThreadLocalImpl.cpp b/src/SFML/System/Unix/ThreadLocalImpl.cpp index c99db448..d7f71b77 100644 --- a/src/SFML/System/Unix/ThreadLocalImpl.cpp +++ b/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 { diff --git a/src/SFML/System/Unix/ThreadLocalImpl.hpp b/src/SFML/System/Unix/ThreadLocalImpl.hpp index de9a74c4..a3ade9d2 100644 --- a/src/SFML/System/Unix/ThreadLocalImpl.hpp +++ b/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 /// diff --git a/src/SFML/System/Win32/MutexImpl.cpp b/src/SFML/System/Win32/MutexImpl.cpp index 17b326e0..2532445b 100644 --- a/src/SFML/System/Win32/MutexImpl.cpp +++ b/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() { diff --git a/src/SFML/System/Win32/MutexImpl.hpp b/src/SFML/System/Win32/MutexImpl.hpp index 1d7df5b6..743a4549 100644 --- a/src/SFML/System/Win32/MutexImpl.hpp +++ b/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(); diff --git a/src/SFML/System/Win32/Platform.cpp b/src/SFML/System/Win32/Platform.cpp index 948d1546..7ad0fb6a 100644 --- a/src/SFML/System/Win32/Platform.cpp +++ b/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) { diff --git a/src/SFML/System/Win32/Platform.hpp b/src/SFML/System/Win32/Platform.hpp index 0baafd40..8c56074f 100644 --- a/src/SFML/System/Win32/Platform.hpp +++ b/src/SFML/System/Win32/Platform.hpp @@ -37,15 +37,15 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// Win32 implementation of Platform. -/// Gives access to various global system functions +/// \brief Gives access to some system-specific low-level 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); diff --git a/src/SFML/System/Win32/ThreadImpl.cpp b/src/SFML/System/Win32/ThreadImpl.cpp index 22ad77eb..2f707a29 100644 --- a/src/SFML/System/Win32/ThreadImpl.cpp +++ b/src/SFML/System/Win32/ThreadImpl.cpp @@ -36,8 +36,6 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// ThreadImpl::ThreadImpl(Thread* owner) { myThread = reinterpret_cast(_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) { diff --git a/src/SFML/System/Win32/ThreadImpl.hpp b/src/SFML/System/Win32/ThreadImpl.hpp index 5e83e71d..92142e01 100644 --- a/src/SFML/System/Win32/ThreadImpl.hpp +++ b/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 - /// Terminating a thread with this function is not safe, - /// you should rather try to make the thread function - /// terminate by itself + /// \brief Terminate the thread /// //////////////////////////////////////////////////////////// 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); diff --git a/src/SFML/System/Win32/ThreadLocalImpl.cpp b/src/SFML/System/Win32/ThreadLocalImpl.cpp index cafa76dc..d5868b92 100644 --- a/src/SFML/System/Win32/ThreadLocalImpl.cpp +++ b/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 { diff --git a/src/SFML/System/Win32/ThreadLocalImpl.hpp b/src/SFML/System/Win32/ThreadLocalImpl.hpp index 2035ecff..cb21cfc1 100644 --- a/src/SFML/System/Win32/ThreadLocalImpl.hpp +++ b/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 ///