Documentation for ObjectRef

Former-commit-id: 3c704ed4e8999b0cdc66f6fe29ca0f170cc6619c

include/Nazara/Core/ObjectRef.inl

@@ -7,12 +7,27 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::ObjectRef
+	* \brief Core class that represents a reference to an object
+	*/
+
+	/*!
+	* \brief Constructs a ObjectRef object by default
+	*/
+
 	template<typename T>
 	ObjectRef<T>::ObjectRef() :
 	m_object(nullptr)
 	{
 	}
 
+	/*!
+	* \brief Constructs a ObjectRef object with a pointer to an object
+	*
+	* \param object Pointer to handle like a reference (can be nullptr)
+	*/
+
 	template<typename T>
 	ObjectRef<T>::ObjectRef(T* object) :
 	m_object(object)
@@ -21,6 +36,12 @@ namespace Nz
 			m_object->AddReference();
 	}
 
+	/*!
+	* \brief Constructs a ObjectRef object by assignation
+	*
+	* \param ref ObjectRef to assign into this
+	*/
+
 	template<typename T>
 	ObjectRef<T>::ObjectRef(const ObjectRef& ref) :
 	m_object(ref.m_object)
@@ -29,6 +50,12 @@ namespace Nz
 			m_object->AddReference();
 	}
 
+	/*!
+	* \brief Constructs a ObjectRef<U> object from another type of ObjectRef
+	*
+	* \param ref ObjectRef of type U to convert to type T
+	*/
+
 	template<typename T>
 	template<typename U>
 	ObjectRef<T>::ObjectRef(const ObjectRef<U>& ref) :
@@ -36,13 +63,23 @@ namespace Nz
 	{
 	}
 
+	/*!
+	* \brief Constructs a ObjectRef object by move semantic
+	*
+	* \param ref ObjectRef to move into this
+	*/
+
 	template<typename T>
 	ObjectRef<T>::ObjectRef(ObjectRef&& ref) noexcept :
 	m_object(ref.m_object)
 	{
-		ref.m_object = nullptr; // On vole la référence
+		ref.m_object = nullptr; // We steal the reference
 	}
 
+	/*!
+	* \brief Destructs the object (remove a reference to the object when shared)
+	*/
+
 	template<typename T>
 	ObjectRef<T>::~ObjectRef()
 	{
@@ -50,27 +87,50 @@ namespace Nz
 			m_object->RemoveReference();
 	}
 
+	/*!
+	* \brief Gets the underlying pointer
+	* \return Underlying pointer
+	*/
+
 	template<typename T>
 	T* ObjectRef<T>::Get() const
 	{
 		return m_object;
 	}
 
+	/*!
+	* \brief Checks whether the reference is valid
+	* \return true if reference is not nullptr
+	*/
+
 	template<typename T>
 	bool ObjectRef<T>::IsValid() const
 	{
 		return m_object != nullptr;
 	}
 
+	/*!
+	* \brief Releases the handle of the pointer
+	* \return Underlying pointer
+	*/
+
 	template<typename T>
 	T* ObjectRef<T>::Release()
 	{
+		if (m_object)
+			m_object->RemoveReference();
+
 		T* object = m_object;
 		m_object = nullptr;
 
 		return object;
 	}
 
+	/*!
+	* \brief Resets the content of the ObjectRef with another pointer
+	* \return true if old handle is destroyed
+	*/
+
 	template<typename T>
 	bool ObjectRef<T>::Reset(T* object)
 	{
@@ -88,6 +148,13 @@ namespace Nz
 		return destroyed;
 	}
 
+	/*!
+	* \brief Swaps the content of the two ObjectRef
+	* \return A reference to this
+	*
+	* \param ref ObjectRef to swap
+	*/
+
 	template<typename T>
 	ObjectRef<T>& ObjectRef<T>::Swap(ObjectRef& ref)
 	{
@@ -96,24 +163,48 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Converts the ObjectRef to bool
+	* \return true if reference is not nullptr
+	*
+	* \see IsValid
+	*/
+
 	template<typename T>
 	ObjectRef<T>::operator bool() const
 	{
 		return IsValid();
 	}
 
+	/*!
+	* \brief Dereferences the ObjectRef
+	* \return Underlying pointer
+	*/
+
 	template<typename T>
 	ObjectRef<T>::operator T*() const
 	{
 		return m_object;
 	}
 
+	/*!
+	* \brief Dereferences the ObjectRef
+	* \return Underlying pointer
+	*/
+
 	template<typename T>
 	T* ObjectRef<T>::operator->() const
 	{
 		return m_object;
 	}
 
+	/*!
+	* \brief Assigns the object into this
+	* \return A reference to this
+	*
+	* \param object Pointer to handle like a reference (can be nullptr)
+	*/
+
 	template<typename T>
 	ObjectRef<T>& ObjectRef<T>::operator=(T* object)
 	{
@@ -122,6 +213,13 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Sets the reference of the ObjectRef with the handle from another
+	* \return A reference to this
+	*
+	* \param ref The other ObjectRef
+	*/
+
 	template<typename T>
 	ObjectRef<T>& ObjectRef<T>::operator=(const ObjectRef& ref)
 	{
@@ -130,6 +228,13 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Sets the reference of the ObjectRef from another type of ObjectRef
+	* \return A reference to this
+	*
+	* \param ref ObjectRef of type U to convert
+	*/
+
 	template<typename T>
 	template<typename U>
 	ObjectRef<T>& ObjectRef<T>::operator=(const ObjectRef<U>& ref)
@@ -141,6 +246,13 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Moves the ObjectRef into this
+	* \return A reference to this
+	*
+	* \param ref ObjectRef to move in this
+	*/
+
 	template<typename T>
 	ObjectRef<T>& ObjectRef<T>::operator=(ObjectRef&& ref) noexcept
 	{
@@ -154,6 +266,13 @@ namespace Nz
 
 namespace std
 {
+	/*!
+	* \brief Gives a hash representation of the object, specialisation of std
+	* \return Hash of the ObjectRef
+	*
+	* \param object Object to hash
+	*/
+
 	template<typename T>
 	struct hash<Nz::ObjectRef<T>>
 	{

tests/Engine/Core/ObjectRef.cpp

@@ -0,0 +1,41 @@
+#include <Nazara/Core/ObjectRef.hpp>
+#include <Catch/catch.hpp>
+
+#include <Nazara/Utility/Font.hpp>
+
+SCENARIO("ObjectRef", "[CORE][OBJECTREF]")
+{
+	GIVEN("A ObjectRef")
+	{
+		Nz::ObjectRef<Nz::Font> objectRef;
+
+		WHEN("We have two objectRef handling the same object")
+		{
+			Nz::Font font;
+
+			objectRef = &font;
+			Nz::ObjectRef<Nz::Font> otherRef(&font);
+
+			THEN("Pointers the same")
+			{
+				REQUIRE(objectRef.IsValid());
+				REQUIRE(otherRef.IsValid());
+			}
+
+			objectRef.Reset(nullptr);
+		}
+
+		WHEN("We assign it to a simple font")
+		{
+			Nz::Font font;
+
+			THEN("Release suppress the reference to the object")
+			{
+				objectRef.Reset(&font);
+				objectRef.Release();
+
+				REQUIRE(!objectRef.IsValid());
+			}
+		}
+	}
+}