Refactoring

Docs/Building.dox

@@ -78,7 +78,8 @@ Assembling APK files also requires **Gradle**. The build can be configured using
 
 @code{.sh}
 mkdir build
-cmake -B build -D CMAKE_BUILD_TYPE=Debug -D NCINE_BUILD_ANDROID=ON -D NCINE_UNIVERSAL_APK=ON -D NCINE_NDK_ARCHITECTURES="arm64-v8a;armeabi-v7a"
+cmake -B build -D CMAKE_BUILD_TYPE=Debug -D NCINE_BUILD_ANDROID=ON \
+    -D NCINE_UNIVERSAL_APK=ON -D NCINE_NDK_ARCHITECTURES="arm64-v8a;armeabi-v7a"
 @endcode
 
 @m_class{m-noindent}
@@ -105,7 +106,8 @@ a similar command as above:
 
 @code{.sh}
 mkdir build
-cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 -D CMAKE_SYSTEM_PROCESSOR=x64 -D NCINE_COPY_DEPENDENCIES=ON
+cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 -D CMAKE_SYSTEM_PROCESSOR=x64 ^
+    -D NCINE_COPY_DEPENDENCIES=ON
 @endcode
 
 @m_class{m-noindent}
@@ -119,10 +121,11 @@ with Clang-CL is also possible specifying `-T ClangCL` parameter.
 @subsection building-uwp Building for Xbox (Universal Windows Platform)
 
 The same commands can be used as for @ref building-windows "Windows",
-but 2 additional parameters must be specified to change the target:
+but two additional parameters must be specified to change the target:
 
 @code{.sh}
-cmake -D CMAKE_SYSTEM_NAME=WindowsStore -D CMAKE_SYSTEM_VERSION="10.0"
+cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 -D CMAKE_SYSTEM_PROCESSOR=x64 ^
+    -D CMAKE_SYSTEM_NAME=WindowsStore -D CMAKE_SYSTEM_VERSION="10.0"
 @endcode
 
 @m_class{m-noindent}
@@ -205,6 +208,7 @@ The following parameters can be used to customize the build:
 -   `DEATH_TRACE` (default `ON`) --- Enable runtime event tracing
 -   `DEATH_TRACE_ASYNC` (default `ON` if `NCINE_WITH_THREADS`) --- Enable asynchronous processing of event tracing for better performance
 -   `NCINE_ARCH_EXTENSIONS` --- Target CPU architecture extensions (instruction sets)
+    -   See [`/arch` docs for MSVC](https://learn.microsoft.com/en-us/cpp/build/reference/arch-minimum-cpu-architecture?view=msvc-170)) and [`-m` docs for GCC](https://gcc.gnu.org/onlinedocs/gcc-8.4.0/gcc/Submodel-Options.html) for more details.
 -   `NCINE_INPUT_DEBUGGING` (default `OFF`) --- Enable (gamepad) input debugging and logging
 -   `NCINE_LINKTIME_OPTIMIZATION` (default `ON`) --- Compile with link time optimization
 -   `NCINE_ADDRESS_SANITIZER` (default `OFF`) --- Enable AddressSanitizer memory error detector

Sources/Jazz2/AnimationLoopMode.h

@@ -5,9 +5,9 @@ namespace Jazz2
 	/** @brief Animation loop mode */
 	enum class AnimationLoopMode
 	{
-		/** @brief The animation is played once an then remains in its last frame */
+		/** @brief The animation is played once and then remains in its last frame */
 		Once,
-		/** @brief The animation is looped: When reaching the last frame, it begins again at the first one */
+		/** @brief The animation is looped --- when reaching the last frame, it begins again at the first one */
 		Loop,
 		/** @brief A fixed, single frame is displayed */
 		FixedSingle

Sources/Jazz2/ContentResolver.h

@@ -56,18 +56,26 @@ namespace Jazz2
 
 		~ContentResolver();
 
+		/** @brief Releases all cached assets */
 		void Release();
 
+		/** @brief Returns path to `"Content"` directory */
 		StringView GetContentPath() const;
+		/** @brief Returns path to `"Cache"` directory */
 		StringView GetCachePath() const;
+		/** @brief Returns path to `"Source"` directory */
 		StringView GetSourcePath() const;
 
+		/** @brief Returns `true` if the application is running in headless mode (i.e., without any display) */
 		bool IsHeadless() const;
+		/** @brief Sets whether the application is running in headless mode */
 		void SetHeadless(bool value);
 
 #if !defined(DEATH_TARGET_EMSCRIPTEN)
+		/** @brief Scans the `"Content"` and `"Cache"` directories for `.pak` files and mounts them  */
 		void RemountPaks();
 #endif
+		/** @brief Tries to find and open a file specified by the path */
 		std::unique_ptr<Stream> OpenContentFile(StringView path);
 
 		void BeginLoading();

Sources/Shared/Core/ITraceSink.h

@@ -41,13 +41,19 @@ namespace Death
 
 	namespace Trace
 	{
-		/** @brief Registers the sink and initializes logger if no sink was attached before */
+		/** @relatesalso ITraceSink
+			@brief Registers the sink and initializes logger if no sink was attached before
+		*/
 		void AttachSink(ITraceSink* sink);
 
-		/** @brief Unregisters the sink and uninitializes logger if no sink left */
+		/** @relatesalso ITraceSink
+			@brief Unregisters the sink and uninitializes logger if no sink left
+		*/
 		void DetachSink(ITraceSink* sink);
 
-		/** @brief Flushes and waits until all prior items are written to all sinks */
+		/** @relatesalso ITraceSink
+			@brief Flushes and waits until all prior items are written to all sinks
+		*/
 		void Flush();
 	}
 }

Sources/Shared/IO/PakFile.h

@@ -11,6 +11,7 @@
 namespace Death { namespace IO {
 //###==##====#=====--==~--~=~- --- -- -  -  -   -
 
+	/** @brief Preferred file compression, used in @ref PakWritter::AddFile() */
 	enum class PakPreferredCompression
 	{
 		None,

Sources/Shared/Utf8.h

@@ -12,7 +12,7 @@ namespace Death { namespace Utf8 {
 //###==##====#=====--==~--~=~- --- -- -  -  -   -
 
 	/**
-		@brief Number of UTF-8 characters in a string
+		@brief Number of characters in a UTF-8 string
 	*/
 	std::size_t GetLength(Containers::ArrayView<const char> text);
 
@@ -48,7 +48,7 @@ namespace Death { namespace Utf8 {
 	}
 
 	/**
-		@brief Convert a UTF-32 character to UTF-8
+		@brief Converts a UTF-32 character to UTF-8
 		@param[in]  character   UTF-32 character to convert
 		@param[out] result      Where to put the UTF-8 result
 
@@ -59,7 +59,14 @@ namespace Death { namespace Utf8 {
 #if defined(DEATH_TARGET_WINDOWS) || defined(DOXYGEN_GENERATING_OUTPUT)
 
 	/**
-		@brief Widen a UTF-8 string to UTF-16 for use with Windows Unicode APIs
+		@brief Widens a UTF-8 string to UTF-16 for use with Windows Unicode APIs
+		
+		Converts a UTF-8 string to a wide-string (UTF-16) representation. The primary purpose of this API
+		is easy interaction with Windows Unicode APIs. If the text is not empty, the returned array
+		contains a sentinel null terminator (i.e., not counted into its size).
+		
+		@partialsupport Available only on @ref DEATH_TARGET_WINDOWS "Windows" to be
+			used when dealing directly with Windows Unicode APIs.
 	*/
 	std::int32_t ToUtf16(wchar_t* destination, std::int32_t destinationSize, const char* source, std::int32_t sourceSize = -1);
 
@@ -88,7 +95,13 @@ namespace Death { namespace Utf8 {
 #endif
 
 	/**
-		@brief Narrow a UTF-16 string to UTF-8 for use with Windows Unicode APIs
+		@brief Narrows a UTF-16 string to UTF-8 for use with Windows Unicode APIs
+		
+		Converts a wide-string (UTF-16) to a UTF-8 representation. The primary purpose is easy
+		interaction with Windows Unicode APIs.
+		
+		@partialsupport Available only on @ref DEATH_TARGET_WINDOWS "Windows" to be
+			used when dealing directly with Windows Unicode APIs.
 	*/
 	std::int32_t FromUtf16(char* destination, std::int32_t destinationSize, const wchar_t* source, std::int32_t sourceSize = -1);
 

Sources/nCine/I18n.h

@@ -70,7 +70,7 @@ namespace nCine
 		static const ExpressionToken* ExtractPluralExpression(StringView nullEntry);
 	};
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates text in singular form using primary translation catalog
 	*/
 	inline StringView _(const char* text)
@@ -80,7 +80,7 @@ namespace nCine
 		return (result ? result : StringView(text));
 	}
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates text in singular form using primary translation catalog and specified @p context
 	*/
 	inline StringView _x(StringView context, const char* text)
@@ -91,7 +91,7 @@ namespace nCine
 		return (result ? result : textView);
 	}
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates text in singular or plural form using primary translation catalog
 	*/
 	inline StringView _n(const char* singular, const char* plural, std::int32_t n)
@@ -103,7 +103,7 @@ namespace nCine
 		return (n == 1 ? singular : plural);
 	}
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates text in singular or plural form using primary translation catalog and specified @p context
 	*/
 	inline StringView _nx(StringView context, const char* singular, const char* plural, std::int32_t n)
@@ -116,12 +116,12 @@ namespace nCine
 		return (n == 1 ? singular : plural);
 	}
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates formatted text in singular form using primary translation catalog
 	*/
 	String _f(const char* text, ...);
 
-	/** @relatesalso I18n
+	/** @relates I18n
 		@brief Translates formatted text in singular or plural form using primary translation catalog
 	*/
 	String _fn(const char* singular, const char* plural, std::int32_t n, ...);