From 6400ba2e28a03e15d626eda3627836b91bfd4154 Mon Sep 17 00:00:00 2001 From: Gawaboumga Date: Mon, 30 May 2016 14:09:51 +0200 Subject: [PATCH] Fix documentation for module: Core Former-commit-id: a79bf956a2759c6056e4e4e2193b8b192c5727c5 --- include/Nazara/Core/Algorithm.inl | 2 +- include/Nazara/Core/ConfigCheck.hpp | 2 +- include/Nazara/Core/HandledObject.inl | 67 ++++++- include/Nazara/Core/ObjectHandle.inl | 265 +++++++++++++++++++++++-- include/Nazara/Core/ParameterList.hpp | 6 +- include/Nazara/Core/ResourceLoader.inl | 2 +- src/Nazara/Core/Core.cpp | 2 +- src/Nazara/Core/File.cpp | 6 +- src/Nazara/Core/ParameterList.cpp | 62 ++++++ tests/Engine/Core/ByteArray.cpp | 20 ++ tests/Engine/Core/File.cpp | 12 +- 11 files changed, 421 insertions(+), 25 deletions(-) diff --git a/include/Nazara/Core/Algorithm.inl b/include/Nazara/Core/Algorithm.inl index 048fae8e9..6997f8d1e 100644 --- a/include/Nazara/Core/Algorithm.inl +++ b/include/Nazara/Core/Algorithm.inl @@ -78,7 +78,7 @@ namespace Nz * \param v Object to hash * * \remark a HashAppend specialization for type T is required - * + * * \see ComputeHash */ template diff --git a/include/Nazara/Core/ConfigCheck.hpp b/include/Nazara/Core/ConfigCheck.hpp index 8329f4ff0..aa1ac5cfa 100644 --- a/include/Nazara/Core/ConfigCheck.hpp +++ b/include/Nazara/Core/ConfigCheck.hpp @@ -12,7 +12,7 @@ #include #define NazaraCheckTypeAndVal(name, type, op, val, err) static_assert(std::is_ ##type ::value && name op val, #type err) -// We fore the value of MANAGE_MEMORY in debug +// We force the value of MANAGE_MEMORY in debug #if defined(NAZARA_DEBUG) && !NAZARA_CORE_MANAGE_MEMORY #undef NAZARA_CORE_MANAGE_MEMORY #define NAZARA_CORE_MANAGE_MEMORY 0 diff --git a/include/Nazara/Core/HandledObject.inl b/include/Nazara/Core/HandledObject.inl index da435302e..6b4d64c45 100644 --- a/include/Nazara/Core/HandledObject.inl +++ b/include/Nazara/Core/HandledObject.inl @@ -10,6 +10,17 @@ namespace Nz { + /*! + * \ingroup core + * \class Nz::HandledObject + * \brief Core class that represents a handled object + */ + + /*! + * \brief Constructs a HandledObject object by assignation + * + * \param object HandledObject to assign into this + */ template HandledObject::HandledObject(const HandledObject& object) { @@ -17,6 +28,11 @@ namespace Nz // Don't copy anything, we're a copy of the object, we have no handle right now } + /*! + * \brief Constructs a HandledObject object by move semantic + * + * \param object HandledObject to move into this + */ template HandledObject::HandledObject(HandledObject&& object) : m_handles(std::move(object.m_handles)) @@ -25,25 +41,46 @@ namespace Nz handle->OnObjectMoved(static_cast(this)); } + /*! + * \brief Destructs the object and calls UnregisterAllHandles + * + * \see UnregisterAllHandles + */ template HandledObject::~HandledObject() { UnregisterAllHandles(); } + /*! + * \brief Creates a ObjectHandle for this + * \return ObjectHandle to this + */ template ObjectHandle HandledObject::CreateHandle() { return ObjectHandle(static_cast(this)); } + /*! + * \brief Sets the reference of the HandledObject with the handle from another + * \return A reference to this + * + * \param object The other HandledObject + */ template HandledObject& HandledObject::operator=(const HandledObject& object) { // Nothing to do - return *this; + return *this; } + /*! + * \brief Moves the HandledObject into this + * \return A reference to this + * + * \param object HandledObject to move in this + */ template HandledObject& HandledObject::operator=(HandledObject&& object) { @@ -54,13 +91,22 @@ namespace Nz return *this; } + /*! + * \brief Registers a handle + * + * \param handle Handle to register + * + * \remark One handle can only be registered once, errors can occur if it's more than once + */ template void HandledObject::RegisterHandle(ObjectHandle* handle) { - ///DOC: Un handle ne doit être enregistré qu'une fois, des erreurs se produisent s'il l'est plus d'une fois m_handles.push_back(handle); } + /*! + * \brief Unregisters all handles + */ template void HandledObject::UnregisterAllHandles() { @@ -71,10 +117,17 @@ namespace Nz m_handles.clear(); } + /*! + * \brief Unregisters a handle + * + * \param handle Handle to unregister + * + * \remark One handle can only be unregistered once, crash can occur if it's more than once + * \remark Produces a NazaraAssert if handle not registered + */ template void HandledObject::UnregisterHandle(ObjectHandle* handle) noexcept { - ///DOC: Un handle ne doit être libéré qu'une fois, et doit faire partie de la liste, sous peine de crash auto it = std::find(m_handles.begin(), m_handles.end(), handle); NazaraAssert(it != m_handles.end(), "Handle not registered"); @@ -83,6 +136,14 @@ namespace Nz m_handles.pop_back(); } + /*! + * \brief Updates one handle with another + * + * \param oldHandle Old handle to replace + * \param newHandle New handle to take place + * + * \remark Produces a NazaraAssert if handle not registered + */ template void HandledObject::UpdateHandle(ObjectHandle* oldHandle, ObjectHandle* newHandle) noexcept { diff --git a/include/Nazara/Core/ObjectHandle.inl b/include/Nazara/Core/ObjectHandle.inl index cfcd6bc0d..ee6e26268 100644 --- a/include/Nazara/Core/ObjectHandle.inl +++ b/include/Nazara/Core/ObjectHandle.inl @@ -9,12 +9,26 @@ namespace Nz { + /*! + * \ingroup core + * \class Nz::ObjectHandle + * \brief Core class that represents a object handle + */ + + /*! + * \brief Constructs a ObjectHandle object by default + */ template ObjectHandle::ObjectHandle() : m_object(nullptr) { } + /*! + * \brief Constructs a ObjectHandle object with a pointer to an object + * + * \param object Pointer to handle like an object (can be nullptr) + */ template ObjectHandle::ObjectHandle(T* object) : ObjectHandle() @@ -22,59 +36,97 @@ namespace Nz Reset(object); } + /*! + * \brief Constructs a ObjectHandle object by assignation + * + * \param handle ObjectHandle to assign into this + */ template - ObjectHandle::ObjectHandle(const ObjectHandle& handle) : + ObjectHandle::ObjectHandle(const ObjectHandle& handle) : ObjectHandle() { Reset(handle); } + /*! + * \brief Constructs a ObjectHandle object by move semantic + * + * \param handle ObjectHandle to move into this + */ template - ObjectHandle::ObjectHandle(ObjectHandle&& handle) noexcept : + ObjectHandle::ObjectHandle(ObjectHandle&& handle) noexcept : ObjectHandle() { Reset(std::move(handle)); } + /*! + * \brief Destructs the object and calls reset with nullptr + * + * \see Reset + */ template ObjectHandle::~ObjectHandle() { Reset(nullptr); } + /*! + * \brief Gets the underlying object + * \return Underlying object + */ template T* ObjectHandle::GetObject() const { return m_object; } + /*! + * \brief Checks whether the object is valid + * \return true if object is not nullptr + */ template bool ObjectHandle::IsValid() const { return m_object != nullptr; } + /*! + * \brief Resets the content of the ObjectHandle with another object + * + * \param object Object to handle + */ template void ObjectHandle::Reset(T* object) { - // Si nous avions déjà une entité, nous devons l'informer que nous ne pointons plus sur elle + // If we already have an entity, we must alert it that we are not pointing to it anymore if (m_object) m_object->UnregisterHandle(this); m_object = object; if (m_object) - // On informe la nouvelle entité que nous pointons sur elle + // We alert the new entity that we are pointing to it m_object->RegisterHandle(this); } + /*! + * \brief Resets the content of this with another object + * + * \param handle New object to handle + */ template - void ObjectHandle::Reset(const ObjectHandle& handle) + void ObjectHandle::Reset(const ObjectHandle& handle) { Reset(handle.GetObject()); } + /*! + * \brief Resets the content of this with another object by move semantic + * + * \param handle New object to handle to move into this + */ template - void ObjectHandle::Reset(ObjectHandle&& handle) noexcept + void ObjectHandle::Reset(ObjectHandle&& handle) noexcept { if (m_object) m_object->UnregisterHandle(this); @@ -87,12 +139,18 @@ namespace Nz } } + /*! + * \brief Swaps the content of the two ObjectHandle + * \return A reference to this + * + * \param handle ObjectHandle to swap + */ template - ObjectHandle& ObjectHandle::Swap(ObjectHandle& handle) + ObjectHandle& ObjectHandle::Swap(ObjectHandle& handle) { - // Comme nous inversons les handles, nous devons prévenir les entités - // La version par défaut de swap (à base de move) aurait fonctionné, - // mais en enregistrant les handles une fois de plus que nécessaire (à cause de la copie temporaire). + // As we swap the two handles, we must alert the entities + // The default version with swap (move) would be working, + // but will register handles one more time (due to temporary copy). if (m_object) { m_object->UnregisterHandle(this); @@ -105,11 +163,15 @@ namespace Nz handle.m_object->RegisterHandle(this); } - // On effectue l'échange + // We do the swap std::swap(m_object, handle.m_object); return *this; } + /*! + * \brief Gives a string representation + * \return A string representation of the object "ObjectHandle(object representation) or Null" + */ template Nz::String ObjectHandle::ToString() const { @@ -125,24 +187,44 @@ namespace Nz return ss; } + /*! + * \brief Converts the ObjectHandle to bool + * \return true if reference is not nullptr + * + * \see IsValid + */ template ObjectHandle::operator bool() const { return IsValid(); } + /*! + * \brief Dereferences the ObjectHandle + * \return Underlying pointer + */ template ObjectHandle::operator T*() const { return m_object; } + /*! + * \brief Dereferences the ObjectHandle + * \return Underlying pointer + */ template T* ObjectHandle::operator->() const { return m_object; } + /*! + * \brief Assigns the entity into this + * \return A reference to this + * + * \param entity Pointer to handle like an object (can be nullptr) + */ template ObjectHandle& ObjectHandle::operator=(T* entity) { @@ -151,22 +233,37 @@ namespace Nz return *this; } + /*! + * \brief Sets the handle of the ObjectHandle with the handle from another + * \return A reference to this + * + * \param handle The other ObjectHandle + */ template - ObjectHandle& ObjectHandle::operator=(const ObjectHandle& handle) + ObjectHandle& ObjectHandle::operator=(const ObjectHandle& handle) { Reset(handle); return *this; } + /*! + * \brief Moves the ObjectHandle into this + * \return A reference to this + * + * \param handle ObjectHandle to move in this + */ template - ObjectHandle& ObjectHandle::operator=(ObjectHandle&& handle) noexcept + ObjectHandle& ObjectHandle::operator=(ObjectHandle&& handle) noexcept { Reset(std::move(handle)); return *this; } + /*! + * \brief Action to do on object destruction + */ template void ObjectHandle::OnObjectDestroyed() { @@ -174,6 +271,9 @@ namespace Nz m_object = nullptr; } + /*! + * \brief Action to do on object move + */ template void ObjectHandle::OnObjectMoved(T* newObject) { @@ -181,114 +281,247 @@ namespace Nz m_object = newObject; } + /*! + * \brief Output operator + * \return The stream + * + * \param out The stream + * \param handle The ObjectHandle to output + */ template std::ostream& operator<<(std::ostream& out, const ObjectHandle& handle) { return handle.ToString(); } + /*! + * \brief Checks whether the first object handle is equal to the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator==(const ObjectHandle& lhs, const ObjectHandle& rhs) { return lhs.GetObject() == rhs.GetObject(); } + /*! + * \brief Checks whether the object is equal to the second object handle + * \return true if it is the case + * + * \param first Object to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator==(const T& lhs, const ObjectHandle& rhs) { return &lhs == rhs.GetObject(); } + /*! + * \brief Checks whether the object handle is equal to the second object + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second Object to compare in right hand side + */ template bool operator==(const ObjectHandle& lhs, const T& rhs) { return lhs.GetObject() == &rhs; } + /*! + * \brief Checks whether the first object handle is equal to the second object handle + * \return false if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator!=(const ObjectHandle& lhs, const ObjectHandle& rhs) { return !(lhs == rhs); } + /*! + * \brief Checks whether the object is equal to the second object handle + * \return false if it is the case + * + * \param first Object to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator!=(const T& lhs, const ObjectHandle& rhs) { return !(lhs == rhs); } + /*! + * \brief Checks whether the object handle is equal to the second object + * \return false if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second Object to compare in right hand side + */ template bool operator!=(const ObjectHandle& lhs, const T& rhs) { return !(lhs == rhs); } + /*! + * \brief Checks whether the first object handle is less than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<(const ObjectHandle& lhs, const ObjectHandle& rhs) { return lhs.m_object < rhs.m_object; } + /*! + * \brief Checks whether the first object handle is less than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<(const T& lhs, const ObjectHandle& rhs) { return &lhs < rhs.m_object; } + /*! + * \brief Checks whether the first object handle is less than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<(const ObjectHandle& lhs, const T& rhs) { return lhs.m_object < &rhs; } + /*! + * \brief Checks whether the first object handle is less or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<=(const ObjectHandle& lhs, const ObjectHandle& rhs) { return !(lhs > rhs); } + /*! + * \brief Checks whether the first object handle is less or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<=(const T& lhs, const ObjectHandle& rhs) { return !(lhs > rhs); } + /*! + * \brief Checks whether the first object handle is less or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator<=(const ObjectHandle& lhs, const T& rhs) { return !(lhs > rhs); } + /*! + * \brief Checks whether the first object handle is greather than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>(const ObjectHandle& lhs, const ObjectHandle& rhs) { return rhs < lhs; } + /*! + * \brief Checks whether the first object handle is greather than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>(const T& lhs, const ObjectHandle& rhs) { return rhs < lhs; } + /*! + * \brief Checks whether the first object handle is greather than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>(const ObjectHandle& lhs, const T& rhs) { return rhs < lhs; } + /*! + * \brief Checks whether the first object handle is greather or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>=(const ObjectHandle& lhs, const ObjectHandle& rhs) { return !(lhs < rhs); } + /*! + * \brief Checks whether the first object handle is greather or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>=(const T& lhs, const ObjectHandle& rhs) { return !(lhs < rhs); } + /*! + * \brief Checks whether the first object handle is greather or equal than the second object handle + * \return true if it is the case + * + * \param first ObjectHandle to compare in left hand side + * \param second ObjectHandle to compare in right hand side + */ template bool operator>=(const ObjectHandle& lhs, const T& rhs) { @@ -301,6 +534,12 @@ namespace Nz namespace std { + /*! + * \brief Swaps two ObjectHandle, specialisation of std + * + * \param lhs First object handle + * \param rhs Second object handle + */ template void swap(Nz::ObjectHandle& lhs, Nz::ObjectHandle& rhs) { diff --git a/include/Nazara/Core/ParameterList.hpp b/include/Nazara/Core/ParameterList.hpp index 119d05cca..751746aea 100644 --- a/include/Nazara/Core/ParameterList.hpp +++ b/include/Nazara/Core/ParameterList.hpp @@ -50,6 +50,8 @@ namespace Nz void SetParameter(const String& name, void* value); void SetParameter(const String& name, void* value, Destructor destructor); + String ToString() const; + ParameterList& operator=(const ParameterList& list); ParameterList& operator=(ParameterList&&) = default; @@ -73,7 +75,7 @@ namespace Nz ParameterType type; union Value { - // On définit un constructeur/destructeur vide, permettant de mettre des classes dans l'union + // We define an empty constructor/destructor, to be able to put classes in the union Value() {} Value(const Value&) {} // Placeholder ~Value() {} @@ -98,4 +100,6 @@ namespace Nz }; } +std::ostream& operator<<(std::ostream& out, const Nz::ParameterList& parameterList); + #endif // NAZARA_PARAMETERLIST_HPP diff --git a/include/Nazara/Core/ResourceLoader.inl b/include/Nazara/Core/ResourceLoader.inl index af0a8a7f0..74e59067d 100644 --- a/include/Nazara/Core/ResourceLoader.inl +++ b/include/Nazara/Core/ResourceLoader.inl @@ -66,7 +66,7 @@ namespace Nz return false; } - File file(path); // Ouvert seulement en cas de besoin + File file(path); // Open only if needed bool found = false; for (Loader& loader : Type::s_loaders) diff --git a/src/Nazara/Core/Core.cpp b/src/Nazara/Core/Core.cpp index 1ccb35212..026e4a247 100644 --- a/src/Nazara/Core/Core.cpp +++ b/src/Nazara/Core/Core.cpp @@ -28,7 +28,7 @@ namespace Nz bool Core::Initialize() { - if (s_moduleReferenceCounter > 0) + if (IsInitialized()) { s_moduleReferenceCounter++; return true; // Already initialized diff --git a/src/Nazara/Core/File.cpp b/src/Nazara/Core/File.cpp index 39e873373..97504b0ee 100644 --- a/src/Nazara/Core/File.cpp +++ b/src/Nazara/Core/File.cpp @@ -385,7 +385,7 @@ namespace Nz } /*! - * \brief Sets the position of the cursor + * \brief Sets the position of the cursor * \return true if cursor is successfully positioned * * \param pos Position of the cursor @@ -404,7 +404,7 @@ namespace Nz } /*! - * \brief Sets the position of the cursor + * \brief Sets the position of the cursor * \return true if cursor is successfully positioned * * \param offset Offset according to the cursor begin position @@ -906,5 +906,5 @@ namespace Nz } return true; - } + }; } diff --git a/src/Nazara/Core/ParameterList.cpp b/src/Nazara/Core/ParameterList.cpp index 371e91b77..abe93c640 100644 --- a/src/Nazara/Core/ParameterList.cpp +++ b/src/Nazara/Core/ParameterList.cpp @@ -607,6 +607,54 @@ namespace Nz parameter.value.ptrVal = value; } + /*! + * \brief Gives a string representation + * \return A string representation of the object: "ParameterList(Name: Type(value), ...)" + */ + String ParameterList::ToString() const + { + StringStream ss; + + ss << "ParameterList("; + for (auto it = m_parameters.cbegin(); it != m_parameters.cend();) + { + ss << it->first << ": "; + switch (it->second.type) + { + case ParameterType_Boolean: + ss << "Boolean(" << String::Boolean(it->second.value.boolVal) << ")"; + break; + case ParameterType_Color: + ss << "Color(" << it->second.value.colorVal.ToString() << ")"; + break; + case ParameterType_Float: + ss << "Float(" << it->second.value.floatVal << ")"; + break; + case ParameterType_Integer: + ss << "Integer(" << it->second.value.intVal << ")"; + break; + case ParameterType_String: + ss << "String(" << it->second.value.stringVal << ")"; + break; + case ParameterType_Pointer: + ss << "Pointer(" << String::Pointer(it->second.value.ptrVal) << ")"; + break; + case ParameterType_Userdata: + ss << "Userdata(" << String::Pointer(it->second.value.userdataVal->ptr) << ")"; + break; + case ParameterType_None: + ss << "None"; + break; + } + + if (++it != m_parameters.cend()) + ss << ", "; + } + ss << ")"; + + return ss; + } + /*! * \brief Sets a userdata parameter named `name` * @@ -724,3 +772,17 @@ namespace Nz } } } + +/*! +* \brief Output operator +* \return The stream +* +* \param out The stream +* \param parameterList The ParameterList to output +*/ + +std::ostream& operator<<(std::ostream& out, const Nz::ParameterList& parameterList) +{ + out << parameterList.ToString(); + return out; +} diff --git a/tests/Engine/Core/ByteArray.cpp b/tests/Engine/Core/ByteArray.cpp index 476643d5e..d085585a5 100644 --- a/tests/Engine/Core/ByteArray.cpp +++ b/tests/Engine/Core/ByteArray.cpp @@ -213,4 +213,24 @@ SCENARIO("ByteArray", "[CORE][BYTEARRAY]") } } } + + GIVEN("A default byte array") + { + Nz::ByteArray defaultByteArray; + + WHEN("We resize") + { + Nz::UInt64 oldSize = defaultByteArray.GetSize(); + REQUIRE(oldSize == 0); + defaultByteArray.Resize(10); + + THEN("Capacity has increased") + { + REQUIRE(defaultByteArray[oldSize] == 0); + + REQUIRE(defaultByteArray.GetCapacity() >= 10); + REQUIRE(defaultByteArray.GetSize() == 10); + } + } + } } diff --git a/tests/Engine/Core/File.cpp b/tests/Engine/Core/File.cpp index 2ddbfebbf..1163a8aad 100644 --- a/tests/Engine/Core/File.cpp +++ b/tests/Engine/Core/File.cpp @@ -32,12 +32,22 @@ SCENARIO("File", "[CORE][FILE]") REQUIRE(Nz::String(message) == "Test String"); } + AND_THEN("We can get its size") + { + REQUIRE(file.GetSize() == 33U); + } + AND_THEN("We close it") { file.Close(); - REQUIRE(file.GetSize() == 33U); CHECK(!file.IsOpen()); } + + AND_THEN("Change its size") + { + file.SetSize(50U); + REQUIRE(file.GetSize() == 50U); + } } WHEN("We delete this file")