📝 Add docstrings to audio

Kerberos/src/Kerberos/Application.cpp

@@ -12,6 +12,17 @@ namespace Kerberos
 {
 	Application* Application::s_Instance = nullptr;
 
+	/**
+	 * @brief Constructs the Application singleton and initializes core subsystems.
+	 *
+	 * Initializes the global Application instance, sets the working directory if provided,
+	 * creates the main window and its event callback, initializes the audio manager and loads a default audio resource,
+	 * creates and registers the ImGui overlay, and initializes the renderer and scripting engine.
+	 *
+	 * @param spec Configuration used to initialize the application. Relevant fields:
+	 *   - spec.Name: window title.
+	 *   - spec.WorkingDirectory: if non-empty, sets the process working directory to this path; otherwise the current path is kept.
+	 */
 	Application::Application(const ApplicationSpecification& spec) 
 	{
 		KBR_PROFILE_FUNCTION();
@@ -49,6 +60,11 @@ namespace Kerberos
 		//m_AudioManager->Play(R"(C:\Users\retek\Music\Technoshock.wav)");
 	}
 
+	/**
+	 * @brief Destroys the Application and cleans up global subsystems.
+	 *
+	 * Performs application teardown tasks, including shutting down the scripting subsystem.
+	 */
 	Application::~Application() 
 	{
 		//Renderer::Shutdown();
@@ -148,4 +164,4 @@ namespace Kerberos
 		for (const auto& func : functions)
 			func();
 	}
-}
+}

Kerberos/src/Kerberos/Application.h

@@ -12,7 +12,26 @@
 
 #include "Audio/AudioManager.h"
 
-namespace Kerberos
+/**
+	 * Holds command-line arguments passed to the application.
+	 *
+	 * Count is the number of arguments; Args is a null-terminated string array of length Count.
+	 */
+
+	/**
+	 * Access a command-line argument by index.
+	 * @param index Index of the argument to retrieve; must be less than Count.
+	 * @returns The argument string at the given index.
+	 * @note Asserts that index < Count.
+	 */
+
+	/**
+	 * Application creation configuration.
+	 *
+	 * Name is the application name. WorkingDirectory is the initial working directory.
+	 * CommandLineArgs contains the captured command-line arguments.
+	 */
+	namespace Kerberos
 {
 	struct ApplicationCommandLineArgs
 	{
@@ -33,6 +52,11 @@ namespace Kerberos
 		ApplicationCommandLineArgs CommandLineArgs;
 	};
 
+	/**
+	 * Create and initialize the application using the provided specification.
+	 * Initializes core systems including the window, renderer, and ImGui layer.
+	 * @param spec Configuration for the application including Name, WorkingDirectory, and CommandLineArgs.
+	 */
 	class Application
 	{
 	public:
@@ -92,4 +116,3 @@ namespace Kerberos
 	Application* CreateApplication(ApplicationCommandLineArgs args);
 
 }
-

Kerberos/src/Kerberos/Assets/Asset.h

@@ -5,6 +5,18 @@
 #include "Kerberos/Log.h"
 
 
+/**
+ * Convert an AssetType value to its corresponding string name.
+ * @param type The AssetType to convert.
+ * @returns A `std::string_view` with the name of the asset type (e.g., "Texture2D", "Mesh", "Scene", "Sound").
+ *          If `type` is not a known AssetType, the function triggers an assertion and returns an empty string.
+ */
+
+/**
+ * Parse a string name and return the corresponding AssetType enum value.
+ * @param str The string representation of the asset type (e.g., "Texture2D", "Mesh", "Scene", "Sound").
+ * @returns The matching `AssetType`. If `str` is unrecognized, the function triggers an assertion and returns `AssetType::Texture2D`.
+ */
 namespace Kerberos
 {
 	using AssetHandle = UUID;

Kerberos/src/Kerberos/Assets/EditorAssetManager.cpp

@@ -22,6 +22,12 @@ namespace Kerberos
 		{ ".wav", AssetType::Sound } // TODO: Add more audio file types when supported
 	};
 
+	/**
+	 * @brief Determines an AssetType based on a file's extension.
+	 *
+	 * @param filepath Filesystem path whose extension is used to infer the asset type.
+	 * @return AssetType The mapped AssetType for the extension, or `AssetType::Texture2D` if the extension is unrecognized (a warning is logged in that case).
+	 */
 	static AssetType AssetTypeFromFileExtension(const std::filesystem::path& filepath)
 	{
 		const std::string extension = filepath.extension().string();
@@ -173,6 +179,17 @@ namespace Kerberos
 		file << out.c_str();
 	}
 
+	/**
+	 * @brief Loads the project's AssetRegistry.kbrar and populates the in-memory asset registry.
+	 *
+	 * Attempts to read and parse the YAML asset registry file located in the project's asset directory
+	 * and restores entries into m_AssetRegistry. Valid registry entries must include Handle, Type, and Path.
+	 * Entries whose Type parses to Texture2D, TextureCube, Mesh, or Sound are added; entries with missing
+	 * fields or unsupported types are reported and skipped (assertions are triggered for invalid/unsupported entries).
+	 *
+	 * @return true if the registry file was loaded and processed successfully, false on file load/parsing errors
+	 *         or if the registry structure is invalid.
+	 */
 	bool EditorAssetManager::DeserializeAssetRegistry()
 	{
 		const std::filesystem::path& assetDirectoryPath = Project::GetAssetDirectory();
@@ -235,4 +252,4 @@ namespace Kerberos
 
 		return true;
 	}
-}
+}

Kerberos/src/Kerberos/Assets/Importers/AssetImporter.cpp

@@ -17,6 +17,16 @@ namespace Kerberos
 			});
 	}
 
+	/**
+	 * @brief Imports an asset according to the provided metadata and returns the created asset.
+	 *
+	 * Selects the appropriate importer based on metadata.Type and delegates the import operation.
+	 * Asserts and returns `nullptr` if the asset type is unsupported.
+	 *
+	 * @param handle Handle to assign to the imported asset.
+	 * @param metadata Metadata describing the asset (includes type and filepath).
+	 * @return Ref<Asset> Reference to the imported asset, or `nullptr` if the asset type is unsupported.
+	 */
 	Ref<Asset> AssetImporter::ImportAsset(const AssetHandle handle, const AssetMetadata& metadata) 
 	{
 		switch (metadata.Type)
@@ -41,4 +51,4 @@ namespace Kerberos
 		KBR_CORE_ASSERT(false, "Unsupported asset type by AssetImporter!");
 		return nullptr;
 	}
-}
+}

Kerberos/src/Kerberos/Assets/Importers/SoundImporter.cpp

@@ -6,13 +6,25 @@
 
 namespace Kerberos
 {
+	/**
+	 * @brief Imports a sound asset using the file path contained in the asset metadata.
+	 *
+	 * @param metadata Asset metadata containing the file path to load.
+	 * @return Ref<Sound> Reference to the loaded Sound.
+	 */
 	Ref<Sound> SoundImporter::ImportSound(AssetHandle, const AssetMetadata& metadata) 
 	{
 		return ImportSound(metadata.Filepath);
 	}
 
+	/**
+	 * @brief Loads a Sound from the given filesystem path.
+	 *
+	 * @param filepath Filesystem path to the sound file to load.
+	 * @return Ref<Sound> Reference to the loaded Sound object.
+	 */
 	Ref<Sound> SoundImporter::ImportSound(const std::filesystem::path& filepath) 
 	{
 		return Application::Get().GetAudioManager()->Load(filepath);
 	}
-}
+}

Kerberos/src/Kerberos/Assets/Importers/SoundImporter.h

@@ -4,6 +4,18 @@
 #include "Kerberos/Assets/AssetMetadata.h"
 #include "Kerberos/Audio/Sound.h"
 
+/**
+ * Import a sound asset identified by an asset handle and its metadata.
+ * @param handle Asset handle that identifies the source asset to import.
+ * @param metadata Metadata describing the asset (format, settings, source info) used during import.
+ * @returns Reference to the imported Sound.
+ */
+
+/**
+ * Import a sound asset from a filesystem path.
+ * @param filepath Filesystem path to the sound file to import.
+ * @returns Reference to the imported Sound.
+ */
 namespace Kerberos
 {
 	class SoundImporter
@@ -12,4 +24,4 @@ namespace Kerberos
 		static Ref<Sound> ImportSound(AssetHandle handle, const AssetMetadata& metadata);
 		static Ref<Sound> ImportSound(const std::filesystem::path& filepath);
 	};
-}
+}

Kerberos/src/Kerberos/Audio/AudioManager.cpp

@@ -8,7 +8,16 @@
 
 namespace Kerberos 
 {
-	AudioManager* AudioManager::Create() 
+	/**
+ * @brief Creates a platform-specific AudioManager instance.
+ *
+ * On Windows builds this returns a new XAudio2AudioManager. On unsupported platforms
+ * the function triggers a core assertion and returns `nullptr`.
+ *
+ * @return AudioManager* Pointer to a heap-allocated AudioManager instance appropriate
+ * for the current platform, or `nullptr` if no implementation exists. Caller takes ownership.
+ */
+AudioManager* AudioManager::Create() 
 	{
 	#ifdef KBR_PLATFORM_WINDOWS
 		return new XAudio2AudioManager();
@@ -17,4 +26,4 @@ namespace Kerberos
 	KBR_CORE_ASSERT(false, "No AudioManager implementation for this platform!");
 	return nullptr;
 }
-}
+}

Kerberos/src/Kerberos/Audio/AudioManager.h

@@ -6,6 +6,77 @@
 #include <filesystem>
 
 
+/**
+ * Abstract interface for audio management and playback.
+ *
+ * Implementations manage sound loading, playback, and per-sound volume/mute controls.
+ */
+
+/**
+ * Initialize the audio subsystem and any backend-specific resources.
+ */
+
+/**
+ * Update the audio subsystem (called per-frame or periodically).
+ */
+
+/**
+ * Shutdown the audio subsystem and release resources.
+ */
+
+/**
+ * Load a sound from disk and return a reference to the loaded Sound.
+ * @param filepath Filesystem path to the sound asset to load.
+ * @returns A Ref<Sound> referencing the loaded sound.
+ */
+
+/**
+ * Play a sound from the given filesystem path.
+ * @param filepath Filesystem path to the sound asset to play.
+ */
+
+/**
+ * Play a previously loaded sound identified by its UUID.
+ * @param soundID UUID of the sound to play.
+ */
+
+/**
+ * Stop playback of a sound identified by its UUID.
+ * @param soundID UUID of the sound to stop.
+ */
+
+/**
+ * Increase the volume of the specified sound by `delta`.
+ * @param soundID UUID of the sound whose volume will be increased.
+ * @param delta Amount to increase the volume by.
+ */
+
+/**
+ * Decrease the volume of the specified sound by `delta`.
+ * @param soundID UUID of the sound whose volume will be decreased.
+ * @param delta Amount to decrease the volume by.
+ */
+
+/**
+ * Set the volume for the specified sound.
+ * @param soundID UUID of the sound whose volume will be set.
+ * @param volume New volume level (typically in the range 0.0 to 1.0).
+ */
+
+/**
+ * Reset the volume of the specified sound to its default level.
+ * @param soundID UUID of the sound whose volume will be reset.
+ */
+
+/**
+ * Mute the specified sound.
+ * @param soundID UUID of the sound to mute.
+ */
+
+/**
+ * Create and return a concrete AudioManager instance.
+ * @returns Pointer to a newly created AudioManager instance; the caller takes ownership and is responsible for deleting it.
+ */
 namespace Kerberos
 {
 	class AudioManager
@@ -36,4 +107,4 @@ namespace Kerberos
 
 		static AudioManager* Create();
 	};
-}
+}