Documentation for Logger

Former-commit-id: b09dda8a542782667070ea8bf912b552dd6b478a

src/Nazara/Core/AbstractLogger.cpp

@@ -11,17 +11,34 @@ namespace Nz
 	namespace
 	{
 		const char* errorType[] = {
-			"Assert failed: ",	// ErrorType_AssertFailed
-			"Internal error: ",	// ErrorType_Internal
-			"Error: ",			// ErrorType_Normal
-			"Warning: "			// ErrorType_Warning
+			"Assert failed: ",  // ErrorType_AssertFailed
+			"Internal error: ", // ErrorType_Internal
+			"Error: ",          // ErrorType_Normal
+			"Warning: "         // ErrorType_Warning
 		};
 
 		static_assert(sizeof(errorType) / sizeof(const char*) == ErrorType_Max + 1, "Error type array is incomplete");
 	}
 
+	/*!
+	* \class Nz::AbstractLogger<T>
+	* \brief Core class that represents the behaviour of the log classes
+	*
+	* \remark This class is abstract
+	*/
+
 	AbstractLogger::~AbstractLogger() = default;
 
+	/*!
+	* \brief Writes the error in StringStream
+	*
+	* \param type Enumeration of type ErrorType
+	* \param error String describing the error
+	* \param line Line number in the file
+	* \param file Filename
+	* \param function Name of the function throwing the error
+	*/
+
 	void AbstractLogger::WriteError(ErrorType type, const String& error, unsigned int line, const char* file, const char* function)
 	{
 		StringStream stream;

src/Nazara/Core/FileLogger.cpp

@@ -12,6 +12,17 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::FileLogger
+	* \brief Core class that represents a file logger
+	*/
+
+	/*!
+	* \brief Constructs a FileLogger object with a file name
+	*
+	* \param logPath Path to log
+	*/
+
 	FileLogger::FileLogger(const String& logPath) :
 	m_outputFile(logPath),
 	m_forceStdOutput(false),
@@ -20,28 +31,64 @@ namespace Nz
 	{
 	}
 
+	/*!
+	* \brief Destructs the object
+	*/
+
 	FileLogger::~FileLogger() = default;
 
+	/*!
+	* \brief Enables the log of the time
+	*
+	* \param enable If true, enables the time log
+	*/
+
 	void FileLogger::EnableTimeLogging(bool enable)
 	{
 		m_timeLoggingEnabled = enable;
 	}
 
+	/*!
+	* \brief Enables the replication to the stdout
+	*
+	* \param enable If true, enables the replication
+	*/
+
 	void FileLogger::EnableStdReplication(bool enable)
 	{
 		m_stdReplicationEnabled = enable;
 	}
 
+	/*!
+	* \brief Checks whether or not the replication to the stdout is enabled
+	* \return true If replication is enabled
+	*/
+
 	bool FileLogger::IsStdReplicationEnabled()
 	{
 		return m_stdReplicationEnabled;
 	}
 
+	/*!
+	* \brief Checks whether or not the logging of the time is enabled
+	* \return true If logging of the time is enabled
+	*/
+
 	bool FileLogger::IsTimeLoggingEnabled()
 	{
 		return m_timeLoggingEnabled;
 	}
 
+	/*!
+	* \brief Writes a string in the log
+	*
+	* \param string String to log
+	*
+	* \remark Produces a NazaraError if file could not be opened
+	*
+	* \see WriteError
+	*/
+
 	void FileLogger::Write(const String& string)
 	{
 		if (m_forceStdOutput || m_stdReplicationEnabled)
@@ -54,8 +101,8 @@ namespace Nz
 
 		// To prevent infinite loops
 		m_forceStdOutput = true;
-		CallOnExit resetOnExit([this] () 
-		{ 
+		CallOnExit resetOnExit([this] ()
+		{
 			m_forceStdOutput = false;
 		});
 
@@ -85,6 +132,18 @@ namespace Nz
 		m_outputFile.Write(stream);
 	}
 
+	/*!
+	* \brief Writes an error in the log
+	*
+	* \param type The error type
+	* \param error The error text
+	* \param line The line the error occurred
+	* \param file The file the error occurred
+	* \param function The function the error occurred
+	*
+	* \see Write
+	*/
+
 	void FileLogger::WriteError(ErrorType type, const String& error, unsigned int line, const char* file, const char* function)
 	{
 		if (m_forceStdOutput || m_stdReplicationEnabled)

src/Nazara/Core/Log.cpp

@@ -15,21 +15,48 @@ namespace Nz
 		StdLogger s_stdLogger;
 	}
 
+	/*!
+	* \class Nz::Log
+	* \brief Core class that represents a logger
+	*/
+
+	/*!
+	* \brief Enables the log
+	*
+	* \param enable If true, enables the log
+	*/
+
 	void Log::Enable(bool enable)
 	{
 		s_enabled = enable;
 	}
 
+	/*!
+	* \brief Gets the logger
+	* \return An abstract pointer to the logger
+	*/
+
 	AbstractLogger* Log::GetLogger()
 	{
 		return s_logger;
 	}
 
+	/*!
+	* \brief Checks whether or not the logging is enabled
+	* \return true If logging is enabled
+	*/
+
 	bool Log::IsEnabled()
 	{
 		return s_enabled;
 	}
 
+	/*!
+	* \brief Sets the logger
+	*
+	* \param logger AbstractLogger to log
+	*/
+
 	void Log::SetLogger(AbstractLogger* logger)
 	{
 		if (s_logger != &s_stdLogger)
@@ -40,28 +67,57 @@ namespace Nz
 			s_logger = &s_stdLogger;
 	}
 
+	/*!
+	* \brief Writes a string in the log
+	*
+	* \param string String to log
+	*
+	* \see WriteError
+	*/
+
 	void Log::Write(const String& string)
 	{
 		if (s_enabled)
 			s_logger->Write(string);
-		
+
 		OnLogWrite(string);
 	}
 
+	/*!
+	* \brief Writes the error in the log
+	*
+	* \param type Type of the error
+	* \param error Message of the error
+	* \param line Line of the error
+	* \param file File of the error
+	* \param function Function of the error
+	*
+	* \see Write
+	*/
+
 	void Log::WriteError(ErrorType type, const String& error, unsigned int line, const char* file, const char* function)
 	{
 		if (s_enabled)
 			s_logger->WriteError(type, error, line, file, function);
-		
+
 		OnLogWriteError(type, error, line, file, function);
 	}
 
+	/*!
+	* \brief Initializes the Log class
+	* \return true if successful
+	*/
+
 	bool Log::Initialize()
 	{
 		SetLogger(new FileLogger());
 		return true;
 	}
 
+	/*!
+	* \brief Unitializes the Log class
+	*/
+
 	void Log::Uninitialize()
 	{
 		SetLogger(nullptr);

src/Nazara/Core/StdLogger.cpp

@@ -13,8 +13,8 @@ namespace Nz
 		const char* errorType[] = {
 			"Assert failed",	// ErrorType_AssertFailed
 			"Internal error",	// ErrorType_Internal
-			"Error",			// ErrorType_Normal
-			"Warning"			// ErrorType_Warning
+			"Error",		// ErrorType_Normal
+			"Warning"		// ErrorType_Warning
 		};
 
 		static_assert(sizeof(errorType) / sizeof(const char*) == ErrorType_Max + 1, "Error type array is incomplete");
@@ -22,15 +22,17 @@ namespace Nz
 
 	/*!
 	* \class Nz::StdLogger
-	* \brief Logger writing to standard output (stdout, stderr)
+	* \brief Core class that represents a logger writing to standard output (stdout, stderr)
 	*/
 
 	StdLogger::~StdLogger() = default;
 
 	/*!
-	* \brief Enable replication to standard output
+	* \brief Enables replication to standard output
 	*
 	* Does nothing, as the std logger always write to standard output
+	*
+	* \param enable Unused argument
 	*/
 
 	void StdLogger::EnableStdReplication(bool enable)
@@ -40,9 +42,8 @@ namespace Nz
 	}
 
 	/*!
-	* \brief Get the standard output replication status
-	*
-	* Always returns true
+	* \brief Gets the standard output replication status
+	* \return Always returns true
 	*/
 
 	bool StdLogger::IsStdReplicationEnabled()
@@ -51,7 +52,8 @@ namespace Nz
 	}
 
 	/*!
-	* Write to the console
+	* \brief Writes to the console
+	*
 	* \param string The log to write to the console
 	*
 	* \see WriteError
@@ -64,7 +66,8 @@ namespace Nz
 	}
 
 	/*!
-	* Write an error to the console
+	* \brief Writes an error to the console
+	*
 	* \param type The error type
 	* \param error The error text
 	* \param line The line the error occurred