Improved the example snippets and added them to tests

This should ensure that the example snippets remain stable and building at all times

Author: Sp3EdeR

CMakeLists.txt

@@ -69,10 +69,7 @@ if (SINGLETON_BUILD_TESTING)
     # If parent did not include CTest, ensure testing is enabled locally.
     enable_testing()
 
-    add_executable(
-        singleton_test
-        test/unit/singleton_test.cpp
-    )
+    add_executable(singleton_test test/unit/singleton_test.cpp)
     set_target_properties(
         singleton_test PROPERTIES
         CXX_STANDARD 11 CXX_STANDARD_REQUIRED TRUE
@@ -88,4 +85,15 @@ if (SINGLETON_BUILD_TESTING)
 
     # Register in ctest
     add_test(NAME singleton_test COMMAND "$<TARGET_FILE:singleton_test>")
+
+    # Build examples, and register as tests in ctest
+    add_executable(example_base_usage doc/example_base_usage.cpp)
+    target_link_libraries(example_base_usage singleton)
+    add_test(NAME example_base_usage COMMAND "$<TARGET_FILE:example_base_usage>")
+    add_executable(example_constructor doc/example_constructor.cpp)
+    target_link_libraries(example_constructor singleton)
+    add_test(NAME example_constructor COMMAND "$<TARGET_FILE:example_constructor>")
+    add_executable(example_full_usage doc/example_full_usage.cpp)
+    target_link_libraries(example_full_usage singleton)
+    add_test(NAME example_full_usage COMMAND "$<TARGET_FILE:example_full_usage>")
 endif()

README.md

@@ -10,6 +10,8 @@ A great issue with singletons normally is that they make unit testing very hard.
 To start using this library, include the `singleton.hpp` file into your code, and inherit from the `Singleton` class in your code and get its instance as follows:
 
 ```cpp
+#include <singleton.hpp>
+
 class MySingleton : public Singleton<MySingleton>
 {
 private:
@@ -87,40 +89,55 @@ protected:
     // A protected allows a mock to subclass this.
     MySingleton()
     {
+        ++m_allocCounter;
     }
     friend BaseType;
-
-    virtual int MyFunction();
+    static int m_allocCounter;
+public:
+    virtual int GetAllocCount()
+    {
+        return m_allocCounter;
+    }
 };
+int MySingleton::m_allocCounter = 0;
 
 int main()
 {
     // This returns the constructed singleton.
     auto& instance = MySingleton::Get();
 
     // This returns the real implementation's result.
-    auto realResult1 = instance.MyFunction();
+    if (instance.GetAllocCount() != 1)
+        return 1;
 
     // This reconstructs the singleton instance and returns the same instance as earlier.
-    auto& instance2 = SingletonTestApi<MySingleton>::Reconstruct()
+    auto& instance2 = testing::SingletonTestApi<MySingleton>::Reconstruct();
 
     // This returns the real implementation's result from the fresh instance.
-    auto realResult2 = instance.MyFunction();
+    if (instance.GetAllocCount() != 2 || &instance != &instance2)
+        return 2;
 
     struct MyMockSingleton : public MySingleton
     {
-        // Override the MyFunction behaviour in the mock.
-        virtual int MyFunction() override;
+        // Override the GetAllocCount behaviour in the mock.
+        virtual int GetAllocCount() override
+        {
+            return -1;
+        }
     };
     MyMockSingleton mock;
 
     // This injects the mock implementation.
     // The real instance is destroyed, the `instance` and `instance2` variables are invalidated.
-    SingletonTestApi<MySingleton>::Inject(&mock);
+    testing::SingletonTestApi<MySingleton>::Inject(&mock);
 
     // This returns the mock implementation.
     auto& instance3 = MySingleton::Get();
 
+    // This calls the mocked GetAllocCount() instead of the normal one.
+    if (instance3.GetAllocCount() != -1)
+        return 3;
+
     return 0;
 }
 ```

doc/example_base_usage.cpp

@@ -0,0 +1,18 @@
+#include <singleton.hpp>
+
+class MySingleton : public Singleton<MySingleton>
+{
+private:
+    MySingleton() = default;
+    friend BaseType;
+};
+
+int main()
+{
+    // This returns the constructed singleton.
+    auto& instance = MySingleton::Get();
+
+    // Call functions on `instance` here.
+
+    return 0;
+}

doc/example_constructor.cpp

@@ -0,0 +1,33 @@
+#include <singleton.hpp>
+
+class MySingleton : public Singleton<MySingleton>
+{
+private:
+    MySingleton(int customArg1, double customArg2)
+    {
+    }
+    friend BaseType;
+};
+
+int main()
+{
+    {
+        // This returns a nullptr, because the singleton is uninitialized.
+        auto instancePtr = MySingleton::TryGet();
+    }
+    {
+        // This returns the constructed singleton.
+        auto& instance = MySingleton::Get(42, 3.1415);
+    }
+    {
+        // This returns a pointer to the initialized singleton.
+        auto instancePtr = MySingleton::TryGet();
+    }
+    {
+        // This returns the same singleton.
+        // The difference in arguments is ignored.
+        auto& instance = MySingleton::Get(42000, -3.1415);
+    }
+
+    return 0;
+}

doc/example_full_usage.cpp

@@ -0,0 +1,60 @@
+#include <singleton.hpp>
+#include <singleton_test.hpp>
+
+class MySingleton : public Singleton<MySingleton>
+{
+protected:
+    // A protected allows a mock to subclass this.
+    MySingleton()
+    {
+        ++m_allocCounter;
+    }
+    friend BaseType;
+    static int m_allocCounter;
+public:
+    virtual int GetAllocCount()
+    {
+        return m_allocCounter;
+    }
+};
+int MySingleton::m_allocCounter = 0;
+
+int main()
+{
+    // This returns the constructed singleton.
+    auto& instance = MySingleton::Get();
+
+    // This returns the real implementation's result.
+    if (instance.GetAllocCount() != 1)
+        return 1;
+
+    // This reconstructs the singleton instance and returns the same instance as earlier.
+    auto& instance2 = testing::SingletonTestApi<MySingleton>::Reconstruct();
+
+    // This returns the real implementation's result from the fresh instance.
+    if (instance.GetAllocCount() != 2 || &instance != &instance2)
+        return 2;
+
+    struct MyMockSingleton : public MySingleton
+    {
+        // Override the GetAllocCount behaviour in the mock.
+        virtual int GetAllocCount() override
+        {
+            return -1;
+        }
+    };
+    MyMockSingleton mock;
+
+    // This injects the mock implementation.
+    // The real instance is destroyed, the `instance` and `instance2` variables are invalidated.
+    testing::SingletonTestApi<MySingleton>::Inject(&mock);
+
+    // This returns the mock implementation.
+    auto& instance3 = MySingleton::Get();
+
+    // This calls the mocked GetAllocCount() instead of the normal one.
+    if (instance3.GetAllocCount() != -1)
+        return 3;
+
+    return 0;
+}