Documentation for RefCounted

Former-commit-id: 45bd646d027ba91fc3d399631fc0518ba172385d

src/Nazara/Core/RefCounted.cpp

@@ -16,12 +16,29 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::RefCounted
+	* \brief Core class that represents a reference with a counter
+	*/
+
+	/*!
+	* \brief Constructs a RefCounted object with a persistance aspect
+	*
+	* \param persistent if false, object is destroyed when no more referenced
+	*/
+
 	RefCounted::RefCounted(bool persistent) :
 	m_persistent(persistent),
 	m_referenceCount(0)
 	{
 	}
 
+	/*!
+	* \brief Destructs the object
+	*
+	* \remark Produces a NazaraWarning if still referenced with NAZARA_CORE_SAFE defined
+	*/
+
 	RefCounted::~RefCounted()
 	{
 		#if NAZARA_CORE_SAFE
@@ -30,21 +47,42 @@ namespace Nz
 		#endif
 	}
 
+	/*!
+	* \brief Adds a reference to the object
+	*/
+
 	void RefCounted::AddReference() const
 	{
 		m_referenceCount++;
 	}
 
+	/*!
+	* \brief Gets the number of references to the object
+	* \return Number of references
+	*/
+
 	unsigned int RefCounted::GetReferenceCount() const
 	{
 		return m_referenceCount;
 	}
 
+	/*!
+	* \brief Checks whether the object is persistent
+	* \return true if object is not destroyed when no more referenced
+	*/
+
 	bool RefCounted::IsPersistent() const
 	{
 		return m_persistent;
 	}
 
+	/*!
+	* \brief Removes a reference to the object
+	* \return true if object is deleted because no more referenced
+	*
+	* \remark Produces a NazaraError if counter is already 0 with NAZARA_CORE_SAFE defined
+	*/
+
 	bool RefCounted::RemoveReference() const
 	{
 		#if NAZARA_CORE_SAFE
@@ -65,6 +103,14 @@ namespace Nz
 			return false;
 	}
 
+	/*!
+	* \brief Sets the persistence of the object
+	* \return true if object is deleted because no more referenced
+	*
+	* \param persistent Sets the persistence of the object
+	* \param checkReferenceCount Checks if the object should be destroyed if true
+	*/
+
 	bool RefCounted::SetPersistent(bool persistent, bool checkReferenceCount)
 	{
 		m_persistent = persistent;

tests/Engine/Core/RefCounted.cpp

@@ -0,0 +1,29 @@
+#include <Nazara/Core/RefCounted.hpp>
+#include <Catch/catch.hpp>
+
+SCENARIO("RefCounted", "[CORE][REFCOUNTED]")
+{
+	GIVEN("A refcounted persistent")
+	{
+		Nz::RefCounted refCounted;
+		REQUIRE(refCounted.IsPersistent() == true);
+
+		WHEN("We add a reference to this persistent object")
+		{
+			THEN("Number of references should be one")
+			{
+				refCounted.AddReference();
+				REQUIRE(refCounted.GetReferenceCount() == 1);
+				REQUIRE(refCounted.RemoveReference() == false);
+			}
+
+			AND_THEN("We suppress the reference, object is still alive")
+			{
+				refCounted.AddReference();
+				REQUIRE(refCounted.IsPersistent());
+				REQUIRE(refCounted.RemoveReference() == false);
+				REQUIRE(refCounted.GetReferenceCount() == 0);
+			}
+		}
+	}
+}