Updated and clarified the documentation

Thread safety guarantees have been documented more precisely.

Author: Sp3EdeR

CMakeLists.txt

@@ -18,6 +18,13 @@ if (UNIX)
     target_link_libraries(singleton INTERFACE Threads::Threads)
 endif()
 
+# Documentation generation using Doxygen
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "README.md")
+    doxygen_add_docs(doc "README.md" include)
+endif()
+
 # Unit Test.
 if (NOT SINGLETON_SKIP_TEST)
     enable_testing()

README.md

@@ -72,15 +72,14 @@ For more information about its usage, see the documentation within the [include/
 
 # Testing
 
-The singleton has private methods which are designed for testing. These methods are normally inaccessible for production code, which is desired for software stability and quality.
+The singleton has an interface designed for testing only. These interfaces should not be used in production code, because the software stability and quality cannot be guaranteed.
 
-The C++ standard states that during explicit template instantiations accessibility checking is not performed. It is possible to exploit this to gain access to private members. Why should we want to get around the accessibility limitation of private members? Because unit tests often need to be able to introspect objects. In the case of this library, the unsafe testing functionality is only accessible by exploiting this behaviour.
-
-While it is complicated and impractical to write the template code to access private members - which is a good thing - there are multiple libraries designed to gain access to this functionality for unit tests. The following example shows the usage of the `Reset()` and `Inject()` methods through the [access_private library](https://github.com/martong/access_private/) by [Gábor Márton](https://github.com/martong).
+To access the testing interfaces, test code can include the `singleton_test.hpp` file. This provides access for the tests to use the `::testing::SingletonTestApi` class.
+The following example shows the usage of the `::testing::SingletonTestApi<T>::Reconstruct()` and `::testing::SingletonTestApi<T>::Inject()` methods.
 
 ```cpp
 #include <singleton.hpp>
-#include <access_private.hpp>
+#include <singleton_test.hpp>
 
 class MySingleton : public Singleton<MySingleton>
 {
@@ -93,8 +92,6 @@ protected:
 
     virtual int MyFunction();
 };
-ACCESS_PRIVATE_STATIC_FUN(MySingleton, MySingleton&(), Reset);
-ACCESS_PRIVATE_STATIC_FUN(MySingleton, void(MySingleton*), Inject);
 
 int main()
 {
@@ -105,7 +102,7 @@ int main()
     auto realResult1 = instance.MyFunction();
 
     // This reconstructs the singleton instance and returns the same instance as earlier.
-    auto& instance2 = call_private_static::MySingleton::Reset();
+    auto& instance2 = SingletonTestApi<MySingleton>::Reconstruct()
 
     // This returns the real implementation's result from the fresh instance.
     auto realResult2 = instance.MyFunction();
@@ -119,7 +116,7 @@ int main()
 
     // This injects the mock implementation.
     // The real instance is destroyed, the `instance` and `instance2` variables are invalidated.
-    call_private_static::MySingleton::Inject(&mock);
+    SingletonTestApi<MySingleton>::Inject(&mock);
 
     // This returns the mock implementation.
     auto& instance3 = MySingleton::Get();
@@ -128,20 +125,10 @@ int main()
 }
 ```
 
-> [!TIP]
-> When the Singleton has a non-trivial constructor, and the `Reset` function is accessed, then each parameter type must be an r-value reference. For example if `MySingleton`'s constructor is:
->
-> ```.cpp
-> MySingleton::MySingleton(FooType arg1, BarType&& arg2);
-> ```
->
-> Then the `Reset` function's signature is:
->
-> ```.cpp
-> MySingleton& MySingleton::Reset(FooType&&, BarType&&);
-> ```
-
 > [!NOTE]
 > To be able to properly use the `Inject` function, the production code should not cache a reference or pointer to the returned instance. Otherwise the injected mock doesn't take effect and the real instance is used, which is destroyed. This may cause a crash or an other memory corruption style issue.
 
-For more examples and "requirements", it is recommended to view this library's [test code](blob/main/test/unit/singleton_test.cpp).
+For more examples and behavioral requirements, it is recommended to view this library's [test code](blob/main/test/unit/singleton_test.cpp).
+
+> [!TIP]
+> Earlier versions of this library used the [access_private library](https://github.com/martong/access_private/) by [Gábor Márton](https://github.com/martong) to access the Singleton's testing-only methods through explicit template instantiation's disabled accessibility check. This method is still supported, but it is untested. In version 2.0, the `Reset` method's signature is changed to use universal references, so `&&` must be added after all parameters.

include/singleton.hpp

@@ -10,28 +10,23 @@
 
 namespace testing
 {
-	// Forward declaration of the testing interface.
+    // Forward declaration of the testing interface.
     template <typename T>
     struct SingletonTestApi;
 }
 
 /// Implements the singleton pattern, but makes unit testing easy.
-/** To use the Singleton class normally, inherit from it with the CRTP style, like:
+/** To use the Singleton class normally, inherit from it with the [CRTP] style, like:
   *
   * ```cpp
   * class MyClass : public Singleton<MyClass> { impl... };
   * ```
   *
   * After this, external code is able to get the `MyClass` instance by using `MyClass::Get()`.
   *
-  * To test your singleton, an access-private library implementation is required, such as
-  * <https://github.com/martong/access_private>. Using the access-private library, invoke the
-  * `MyClass::Inject()` function to inject a mock implementation into the singleton. It is also
-  * possible to reconstruct the Singleton with different constructor arguments by using the
-  * `MyClass::Reset()` function.
-  *
-  * @remark The `Inject()` and `Reset()` functions are NOT thread safe! They should only be used
-  *         in test code sections while implementation code is not running on a different thread.
+  * To test your singleton, use `::testing::SingletonTestApi<T>` from `singleton_test.hpp`.
+  * 
+  * [CRTP]: https://en.cppreference.com/w/cpp/language/crtp.html
   */
 template <typename T>
 struct Singleton
@@ -42,7 +37,7 @@ struct Singleton
     /// Returns the instance of the class.
     /** @remark The constructor arguments are only used if the instance is not constructed yet.
                 On subsequent calls, get may be called without arguments. Use `TryGet()` instead to
-				check if the instance is already constructed.
+                check if the instance is already constructed.
       */
     template <typename ...Args>
     static T& Get(Args&&... args)
@@ -59,6 +54,7 @@ struct Singleton
       */
     static T* TryGet() noexcept
     {
+        // NOTE: Thread safety here assumes that pointers can be read/written atomically.
         return g_instance;
     }
 
@@ -73,15 +69,19 @@ struct Singleton
     {
         Instance() noexcept = default;
         Instance(const Instance&) = delete;
-		~Instance()
+        ~Instance()
         {
             // Destroys the locally-initialized instance. Injected ones are ignored (no ownership).
             if (m_pExtern == LOCAL_INSTANCE_ID)
                 GetBuffer().~T();
         }
         Instance& operator =(const Instance&) = delete;
         /// Returns the current instance.
-        operator T* () noexcept { return m_pExtern == LOCAL_INSTANCE_ID ? &GetBuffer() : m_pExtern; }
+        operator T* () noexcept
+        {
+            // m_pExtern is used only by test code, so thread safety is not a concern here.
+            return m_pExtern == LOCAL_INSTANCE_ID ? &GetBuffer() : m_pExtern;
+        }
         /// Constructs the singleton within the local buffer.
         template <typename ...Args>
         void Emplace(Args&&... args)
@@ -96,7 +96,7 @@ struct Singleton
             {
                 m_pExtern = nullptr;
                 throw;
-			}
+            }
         }
         /// Sets an external object as the instance.
         /** @remark If `ptr` is `nullptr`, this is just reset.
@@ -149,7 +149,7 @@ struct Singleton
         union U { std::once_flag asOnceFlag; U(){} ~U(){} } buffer;
     } g_onceFlag;
 
-	/// Internal function, use the `::testing::SingletonTestApi<T>::Reconstruct()` function instead.
+    /// Internal function, use the `::testing::SingletonTestApi<T>::Reconstruct()` function instead.
     template <typename ...Args>
     static T& Reset(Args&&... args)
     {
@@ -158,7 +158,7 @@ struct Singleton
     }
 
     /// Internal function, use the `::testing::SingletonTestApi<T>::Inject()` function instead.
-	static void Inject(T* object)
+    static void Inject(T* object)
     {
         if (object)
             std::call_once(g_onceFlag, []() {});
@@ -176,7 +176,7 @@ struct Singleton
         g_instance.Emplace(std::forward<Args>(args)...);
     }
 
-	// The testing interface can access testing-only functions.
+    // The testing interface can access testing-only functions.
     friend struct testing::SingletonTestApi<T>;
 };
 template <typename T>

include/singleton_test.hpp

@@ -4,62 +4,87 @@
 /** @file
   * @brief Provides testing functions for Singleton<T>.
   * 
-  * This file should only be included in unit tests. The unit test code should be added to the
-  * `::testing` namespace, from which the provided interfaces are directly usable.
+  * @warning DO NOT USE THIS FILE IN PRODUCTION CODE!  
+  * This interface bypasses the singleton's encapsulation and exposes functions intended for
+  * unit testing only.
+  *
+  * The unit test code should be added to the `::testing` namespace, from which the provided
+  * interfaces are directly usable.
   */
 
 #include "singleton.hpp"
 
 namespace testing
 {
     /// Provides access to Singleton's testing functions.
-    /** @warning DO NOT USE THIS IN PRODUCTION CODE
-      * This interface bypasses the singleton's encapsulation and exposes functions intended for unit
-      * testing only.
+    /** @warning DO NOT USE THIS IN PRODUCTION CODE!  
+      * This interface bypasses the singleton's encapsulation and exposes functions intended for
+      * unit testing only.
+      * 
+      * Invoke the `Inject()` method to inject a mock implementation into the singleton. It is also
+      * possible to reconstruct the Singleton with different constructor arguments by using the
+      * `Reconstruct()` method.
       * 
       * Usage:
       * 
       * ```cpp
-      * testing::SingletonTestApi<MySingletonType>::Reset(constructorArg1, constructorArg2);
+      * testing::SingletonTestApi<MySingletonType>::Reconstruct(constructorArg1, constructorArg2);
       * testing::SingletonTestApi<MySingletonType>::Inject(&myMockInstance);
       * ```
+      *
+      * @remark This class's methods are NOT thread safe! They should only be used in test code
+      *         sections while implementation code is not running on a different thread.
       */
     template <typename T>
     struct SingletonTestApi
     {
         /// (Re)constructs the internal singleton instance.
-        /** If an existing singleton instance was already constructed, it is destroyed. If an external
-          * instance was injected, it is overridden with the newly constructed instance.
-          *
-          * @remark This function is not thread safe. It is intended for tests, not production code.
+        /** If an existing singleton instance was already constructed, it is destroyed. If an
+          * external instance was injected, it is overridden with the newly constructed internal
+          * instance.
+          * @remark This function is not thread safe. It is intended for tests, not production
+          *         code. Do not call this function twice, or any of the same singleton's getter
+          *         functions at the same time.
           */
         template <typename ...Args>
         static T& Reconstruct(Args&&... args)
         {
             return SingletonType::Reset(std::forward<Args>(args)...);
         }
 
-        /// @overload
+        /// This is an alias for `Reconstruct()`.
+        /** It is recommended to use `Reconstruct()`, because it is more descriptive.
+          */
         template <typename ...Args>
         static T& Reset(Args&&... args)
         {
             return SingletonType::Reset(std::forward<Args>(args)...);
         }
 
         /// Injects an external instance into the singleton.
-        /** If an external instance is injected, the `Get()` function
-          * @param object The object is taken without ownership and must be deleted by the caller.
-          * @remark If `object` is `nullptr`, it resets the singleton to uninitialized state, and the
+        /** The injected class instance is returned on the upcoming calls to the `Singleton<T>::Get()`
+          * function.
+          *
+          * If an existing singleton instance was already constructed, it is destroyed.
+          *
+          * If `object` is `nullptr`, it resets the singleton to uninitialized state, and the
           *         next invocation of `Get()` reconstructs the instance.
+          * @param object The object is taken without ownership and must be deleted by the caller.
+          * @remark This function is not thread safe. It is intended for tests, not production
+          *         code. Do not call this function twice, or any of the same singleton's getter
+          *         functions at the same time.
           */
         static void Inject(T* object)
         {
             SingletonType::Inject(object);
         }
 
-		/// Resets the singleton to uninitialized state.
-        /** @remark This is an alias for `Inject(nullptr)`.
-		  */
+        /// Resets the singleton to uninitialized state.
+        /** This is an alias for `Inject()` with a `nullptr` argument.
+          * @remark This function is not thread safe. It is intended for tests, not production
+          *         code. Do not call this function twice, or any of the same singleton's getter
+          *         functions at the same time.
+          */
         static void Clear()
         {
             SingletonType::Inject(nullptr);