Documentation for Resource

Former-commit-id: 7da8bc4261566c89030eb0226a29b1a70183e68a

include/Nazara/Core/ResourceLoader.inl

@@ -11,6 +11,18 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::ResourceLoader<Type, Parameters>
+	* \brief Core class that represents a loader of resources
+	*/
+
+	/*!
+	* \brief Checks whether the extension of the file is supported
+	* \return true if supported
+	*
+	* \param extension Extension of the file
+	*/
+
 	template<typename Type, typename Parameters>
 	bool ResourceLoader<Type, Parameters>::IsExtensionSupported(const String& extension)
 	{
@@ -25,10 +37,32 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Loads a resource from a filepath and parameters
+	* \return true if successfully loaded
+	*
+	* \param resource Resource to load
+	* \param filePath Path to the resource
+	* \param parameters Parameters for the load
+	*
+	* \remark Produces a NazaraError if resource is nullptr with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if parameters are invalid with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if filePath has no extension
+	* \remark Produces a NazaraError if file count not be opened
+	* \remark Produces a NazaraWarning if loader failed
+	* \remark Produces a NazaraError if all loaders failed or no loader was found
+	*/
+
 	template<typename Type, typename Parameters>
 	bool ResourceLoader<Type, Parameters>::LoadFromFile(Type* resource, const String& filePath, const Parameters& parameters)
 	{
 		#if NAZARA_CORE_SAFE
+		if (!resource)
+		{
+			NazaraError("Pointer invalid");
+			return false;
+		}
+
 		if (!parameters.IsValid())
 		{
 			NazaraError("Invalid parameters");
@@ -122,13 +156,29 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Loads a resource from a raw memory, a size and parameters
+	* \return true if successfully loaded
+	*
+	* \param resource Resource to load
+	* \param data Raw memory of the resource
+	* \param size Size available for the read
+	* \param parameters Parameters for the load
+	*
+	* \remark Produces a NazaraError if resource is nullptr with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if size is 0 with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if parameters are invalid with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraWarning if loader failed
+	* \remark Produces a NazaraError if all loaders failed or no loader was found
+	*/
+
 	template<typename Type, typename Parameters>
 	bool ResourceLoader<Type, Parameters>::LoadFromMemory(Type* resource, const void* data, unsigned int size, const Parameters& parameters)
 	{
 		#if NAZARA_CORE_SAFE
-		if (!parameters.IsValid())
+		if (!resource)
 		{
-			NazaraError("Invalid parameters");
+			NazaraError("Pointer invalid");
 			return false;
 		}
 
@@ -137,6 +187,12 @@ namespace Nz
 			NazaraError("No data to load");
 			return false;
 		}
+
+		if (!parameters.IsValid())
+		{
+			NazaraError("Invalid parameters");
+			return false;
+		}
 		#endif
 
 		MemoryView stream(data, size);
@@ -198,13 +254,28 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Loads a resource from a stream and parameters
+	* \return true if successfully loaded
+	*
+	* \param resource Resource to load
+	* \param stream Stream of the resource
+	* \param parameters Parameters for the load
+	*
+	* \remark Produces a NazaraError if resource is nullptr with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if stream has no data with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraError if parameters are invalid with NAZARA_CORE_SAFE defined
+	* \remark Produces a NazaraWarning if loader failed
+	* \remark Produces a NazaraError if all loaders failed or no loader was found
+	*/
+
 	template<typename Type, typename Parameters>
 	bool ResourceLoader<Type, Parameters>::LoadFromStream(Type* resource, Stream& stream, const Parameters& parameters)
 	{
 		#if NAZARA_CORE_SAFE
-		if (!parameters.IsValid())
+		if (!resource)
 		{
-			NazaraError("Invalid parameters");
+			NazaraError("Pointer invalid");
 			return false;
 		}
 
@@ -213,6 +284,12 @@ namespace Nz
 			NazaraError("No data to load");
 			return false;
 		}
+
+		if (!parameters.IsValid())
+		{
+			NazaraError("Invalid parameters");
+			return false;
+		}
 		#endif
 
 		UInt64 streamPos = stream.GetCursorPos();
@@ -224,17 +301,17 @@ namespace Nz
 
 			stream.SetCursorPos(streamPos);
 
-			// Le loader supporte-t-il les données ?
+			// Does the loader support these data ?
 			Ternary recognized = checkFunc(stream, parameters);
 			if (recognized == Ternary_False)
 				continue;
 			else if (recognized == Ternary_True)
 				found = true;
 
-			// On repositionne le stream à son ancienne position
+			// We move the stream to its old position
 			stream.SetCursorPos(streamPos);
 
-			// Chargement de la ressource
+			// Load of the resource
 			if (streamLoader(resource, stream, parameters))
 				return true;
 
@@ -250,6 +327,16 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Registers the loader
+	*
+	* \param extensionGetter A function to test whether the extension (as a string) is supported by this loader
+	* \param checkFunc A function to check the stream with the parser
+	* \param streamLoader A function to load the data from a stream in the resource
+	* \param fileLoader Optional function to load the data from a file in the resource
+	* \param memoryLoader Optional function to load the data from a raw memory in the resource
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceLoader<Type, Parameters>::RegisterLoader(ExtensionGetter extensionGetter, StreamChecker checkFunc, StreamLoader streamLoader, FileLoader fileLoader, MemoryLoader memoryLoader)
 	{
@@ -272,6 +359,16 @@ namespace Nz
 		Type::s_loaders.push_front(std::make_tuple(extensionGetter, checkFunc, streamLoader, fileLoader, memoryLoader));
 	}
 
+	/*!
+	* \brief Unregisters the loader
+	*
+	* \param extensionGetter A function to test whether the extension (as a string) is supported by this loader
+	* \param checkFunc A function to check the stream with the parser
+	* \param streamLoader A function to load the data from a stream in the resource
+	* \param fileLoader Optional function to load the data from a file in the resource
+	* \param memoryLoader Optional function to load the data from a raw memory in the resource
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceLoader<Type, Parameters>::UnregisterLoader(ExtensionGetter extensionGetter, StreamChecker checkFunc, StreamLoader streamLoader, FileLoader fileLoader, MemoryLoader memoryLoader)
 	{

include/Nazara/Core/ResourceManager.inl

@@ -9,12 +9,28 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::ResourceManager<Type, Parameters>
+	* \brief Core class that represents a resource manager
+	*/
+
+	/*!
+	* \brief Clears the content of the manager
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::Clear()
 	{
 		Type::s_managerMap.clear();
 	}
 
+	/*!
+	* \brief Gets a reference to the object loaded from file
+	* \return Reference to the object
+	*
+	* \param filePath Path to the asset that will be loaded
+	*/
+
 	template<typename Type, typename Parameters>
 	ObjectRef<Type> ResourceManager<Type, Parameters>::Get(const String& filePath)
 	{
@@ -43,12 +59,21 @@ namespace Nz
 		return it->second;
 	}
 
+	/*!
+	* \brief Gets the defaults parameters for the load
+	* \return Default parameters for loading from file
+	*/
+
 	template<typename Type, typename Parameters>
 	const Parameters& ResourceManager<Type, Parameters>::GetDefaultParameters()
 	{
 		return Type::s_managerParameters;
 	}
 
+	/*!
+	* \brief Purges the resource manager from every asset whose it is the only owner
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::Purge()
 	{
@@ -56,16 +81,23 @@ namespace Nz
 		while (it != Type::s_managerMap.end())
 		{
 			const ObjectRef<Type>& ref = it->second;
-			if (ref.GetReferenceCount() == 1) // Sommes-nous les seuls à détenir la ressource ?
+			if (ref.GetReferenceCount() == 1) // Are we the only ones to own the resource ?
 			{
 				NazaraDebug("Purging resource from file " + ref->GetFilePath());
-				Type::s_managerMap.erase(it++); // Alors on la supprime
+				Type::s_managerMap.erase(it++); // Then we erase it
 			}
 			else
 				++it;
 		}
 	}
 
+	/*!
+	* \brief Registers the resource under the filePath
+	*
+	* \param filePath Path for the resource
+	* \param resource Object to associate with
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::Register(const String& filePath, ObjectRef<Type> resource)
 	{
@@ -74,12 +106,24 @@ namespace Nz
 		Type::s_managerMap[absolutePath] = resource;
 	}
 
+	/*!
+	* \brief Sets the defaults parameters for the load
+	*
+	* \param params Default parameters for loading from file
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::SetDefaultParameters(const Parameters& params)
 	{
 		Type::s_managerParameters = params;
 	}
 
+	/*!
+	* \brief Unregisters the resource under the filePath
+	*
+	* \param filePath Path for the resource
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::Unregister(const String& filePath)
 	{
@@ -88,12 +132,21 @@ namespace Nz
 		Type::s_managerMap.erase(absolutePath);
 	}
 
+	/*!
+	* \brief Initializes the resource manager
+	* \return true
+	*/
+
 	template<typename Type, typename Parameters>
 	bool ResourceManager<Type, Parameters>::Initialize()
 	{
 		return true;
 	}
 
+	/*!
+	* \brief Uninitialize the resource manager
+	*/
+
 	template<typename Type, typename Parameters>
 	void ResourceManager<Type, Parameters>::Uninitialize()
 	{

src/Nazara/Core/Resource.cpp

@@ -7,13 +7,29 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::Resource
+	* \brief Core class that represents a resource
+	*/
+
 	Resource::~Resource() = default;
 
+	/*!
+	* \brief Gets the file path associated with the resource
+	* \return A reference to the path
+	*/
+
 	const String& Resource::GetFilePath() const
 	{
 		return m_filePath;
 	}
 
+	/*!
+	* \brief Sets the file path associated with the resource
+	*
+	* \param filePath Path to the resource
+	*/
+
 	void Resource::SetFilePath(const String& filePath)
 	{
 		m_filePath = filePath;