From 7ec392eda3345606f0de75a432954b221cee82ce Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Wed, 13 Nov 2024 15:40:01 +0100
Subject: add doxygen + check const correctness

---
 src/crepe/api/BehaviorScript.h      |  8 ++++++++
 src/crepe/api/Config.h              |  3 +--
 src/crepe/api/Script.h              | 40 +++++++++++++++++++++++++++++++++++--
 src/crepe/api/Script.hpp            |  8 +++++---
 src/crepe/api/Texture.cpp           |  2 +-
 src/crepe/facade/Sound.cpp          |  9 +++++----
 src/crepe/facade/Sound.h            |  6 ++++++
 src/crepe/facade/SoundContext.h     | 11 +++++++---
 src/crepe/system/PhysicsSystem.h    |  1 +
 src/crepe/system/ScriptSystem.h     | 19 ++++++++++++++++++
 src/crepe/system/System.h           | 10 ++++++++++
 src/example/audio_internal.cpp      |  4 ++--
 src/example/components_internal.cpp |  2 +-
 src/example/db.cpp                  |  8 ++++----
 src/example/proxy.cpp               |  9 ++++-----
 src/example/rendering.cpp           |  2 +-
 src/example/savemgr.cpp             | 16 +++++++--------
 src/example/script.cpp              |  6 +++---
 18 files changed, 125 insertions(+), 39 deletions(-)

diff --git a/src/crepe/api/BehaviorScript.h b/src/crepe/api/BehaviorScript.h
index c20842d..4160a72 100644
--- a/src/crepe/api/BehaviorScript.h
+++ b/src/crepe/api/BehaviorScript.h
@@ -10,6 +10,13 @@ class ScriptSystem;
 class ComponentManager;
 class Script;
 
+/**
+ * \brief Script component
+ *
+ * This class acts as a (component) wrapper around an instance of (a class
+ * derivatived from) \c Script. \c BehaviorScript is the only ECS component
+ * that stores member function implementations as data.
+ */
 class BehaviorScript : public Component {
 protected:
 	friend class crepe::ComponentManager;
@@ -24,6 +31,7 @@ public:
 
 protected:
 	friend class crepe::ScriptSystem;
+	//! Script instance
 	std::unique_ptr<Script> script = nullptr;
 };
 
diff --git a/src/crepe/api/Config.h b/src/crepe/api/Config.h
index 8fd381e..dad7e08 100644
--- a/src/crepe/api/Config.h
+++ b/src/crepe/api/Config.h
@@ -7,7 +7,6 @@ namespace crepe {
 class Config {
 private:
 	Config() = default;
-
 public:
 	~Config() = default;
 
@@ -26,7 +25,7 @@ public:
 		/**
 		 * \brief Log level
 		 *
-		 * Only messages with equal or higher priority than this value will be
+		 * Only messages with equal or higher severity than this value will be
 		 * logged.
 		 */
 		Log::Level level = Log::Level::INFO;
diff --git a/src/crepe/api/Script.h b/src/crepe/api/Script.h
index ed247ad..e6fbb5c 100644
--- a/src/crepe/api/Script.h
+++ b/src/crepe/api/Script.h
@@ -7,11 +7,30 @@ namespace crepe {
 class ScriptSystem;
 class BehaviorScript;
 
+/**
+ * \brief Script interface
+ *
+ * This class is used as a base class for user-defined scripts that can be
+ * added to game objects using the \c BehaviorScript component.
+ */
 class Script {
 	friend class crepe::ScriptSystem;
 
 protected:
+	/**
+	 * \brief Script initialization function
+	 *
+	 * This function is called during the ScriptSystem::update() routine *before*
+	 * Script::update() if it (a) has not yet been called and (b) the \c
+	 * BehaviorScript component holding this script instance is active.
+	 */
 	virtual void init() {}
+	/**
+	 * \brief Script update function
+	 *
+	 * This function is called during the ScriptSystem::update() routine if the
+	 * \c BehaviorScript component holding this script instance is active.
+	 */
 	virtual void update() {}
 	// NOTE: additional *events* (like unity's OnDisable and OnEnable) should be
 	// implemented as member methods in derivative user script classes and
@@ -19,11 +38,28 @@ protected:
 	// added event.
 
 protected:
+	/**
+	 * \brief Get single component of type \c T on this game object (utility)
+	 *
+	 * \tparam T Type of component
+	 *
+	 * \returns Reference to component
+	 *
+	 * \throws nullptr if this game object does not have a component matching
+	 * type \c T
+	 */
 	template <typename T>
-	T & get_component();
+	T & get_component() const;
 
+	/**
+	 * \brief Get all components of type \c T on this game object (utility)
+	 *
+	 * \tparam T Type of component
+	 *
+	 * \returns List of component references
+	 */
 	template <typename T>
-	std::vector<std::reference_wrapper<T>> get_components();
+	std::vector<std::reference_wrapper<T>> get_components() const;
 
 private:
 	friend class crepe::BehaviorScript;
diff --git a/src/crepe/api/Script.hpp b/src/crepe/api/Script.hpp
index d96c0e8..afe653f 100644
--- a/src/crepe/api/Script.hpp
+++ b/src/crepe/api/Script.hpp
@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../ComponentManager.h"
+#include "../Exception.h"
 
 #include "BehaviorScript.h"
 #include "Script.h"
@@ -8,16 +9,17 @@
 namespace crepe {
 
 template <typename T>
-T & Script::get_component() {
+T & Script::get_component() const {
 	std::vector<std::reference_wrapper<T>> all_components
 		= this->get_components<T>();
-	if (all_components.size() < 1) throw nullptr; // TODO
+	if (all_components.size() < 1)
+		throw Exception("Script: no component found with type = %s", typeid(T).name());
 
 	return all_components.back().get();
 }
 
 template <typename T>
-std::vector<std::reference_wrapper<T>> Script::get_components() {
+std::vector<std::reference_wrapper<T>> Script::get_components() const {
 	ComponentManager & mgr = ComponentManager::get_instance();
 	return mgr.get_components_by_id<T>(this->parent->game_object_id);
 }
diff --git a/src/crepe/api/Texture.cpp b/src/crepe/api/Texture.cpp
index 8ddeac5..de0d0ea 100644
--- a/src/crepe/api/Texture.cpp
+++ b/src/crepe/api/Texture.cpp
@@ -26,7 +26,7 @@ Texture::~Texture() {
 
 void Texture::load(unique_ptr<Asset> res) {
 	SDLContext & ctx = SDLContext::get_instance();
-	this->texture = std::move(ctx.texture_from_path(res->canonical()));
+	this->texture = std::move(ctx.texture_from_path(res->get_canonical()));
 }
 
 int Texture::get_width() const {
diff --git a/src/crepe/facade/Sound.cpp b/src/crepe/facade/Sound.cpp
index 49fb8dc..a65b052 100644
--- a/src/crepe/facade/Sound.cpp
+++ b/src/crepe/facade/Sound.cpp
@@ -4,19 +4,20 @@
 #include "SoundContext.h"
 
 using namespace crepe;
+using namespace std;
 
-Sound::Sound(std::unique_ptr<Asset> res) {
+Sound::Sound(unique_ptr<Asset> res) {
 	dbg_trace();
 	this->load(std::move(res));
 }
 
 Sound::Sound(const char * src) {
 	dbg_trace();
-	this->load(std::make_unique<Asset>(src));
+	this->load(make_unique<Asset>(src));
 }
 
-void Sound::load(std::unique_ptr<Asset> res) {
-	this->sample.load(res->canonical());
+void Sound::load(unique_ptr<Asset> res) {
+	this->sample.load(res->get_canonical().c_str());
 }
 
 void Sound::play() {
diff --git a/src/crepe/facade/Sound.h b/src/crepe/facade/Sound.h
index 183bd7c..402482f 100644
--- a/src/crepe/facade/Sound.h
+++ b/src/crepe/facade/Sound.h
@@ -8,6 +8,12 @@
 
 namespace crepe {
 
+/**
+ * \brief Sound resource facade
+ *
+ * This class is a wrapper around a \c SoLoud::Wav instance, which holds a
+ * single sample. It is part of the sound facade.
+ */
 class Sound {
 public:
 	/**
diff --git a/src/crepe/facade/SoundContext.h b/src/crepe/facade/SoundContext.h
index d3123d2..d703c16 100644
--- a/src/crepe/facade/SoundContext.h
+++ b/src/crepe/facade/SoundContext.h
@@ -6,19 +6,24 @@
 
 namespace crepe {
 
+/**
+ * \brief Sound engine facade
+ *
+ * This class is a wrapper around a \c SoLoud::Soloud instance, which provides
+ * the methods for playing \c Sound instances. It is part of the sound facade.
+ */
 class SoundContext {
 private:
+	// singleton
 	SoundContext();
 	virtual ~SoundContext();
-
-	// singleton
-	static SoundContext & get_instance();
 	SoundContext(const SoundContext &) = delete;
 	SoundContext(SoundContext &&) = delete;
 	SoundContext & operator=(const SoundContext &) = delete;
 	SoundContext & operator=(SoundContext &&) = delete;
 
 private:
+	static SoundContext & get_instance();
 	SoLoud::Soloud engine;
 	friend class Sound;
 };
diff --git a/src/crepe/system/PhysicsSystem.h b/src/crepe/system/PhysicsSystem.h
index cc13b70..cb6160e 100644
--- a/src/crepe/system/PhysicsSystem.h
+++ b/src/crepe/system/PhysicsSystem.h
@@ -1,6 +1,7 @@
 #pragma once
 
 namespace crepe {
+
 /**
  * \brief System that controls all physics
  * 
diff --git a/src/crepe/system/ScriptSystem.h b/src/crepe/system/ScriptSystem.h
index f3d26d4..9d57640 100644
--- a/src/crepe/system/ScriptSystem.h
+++ b/src/crepe/system/ScriptSystem.h
@@ -8,12 +8,31 @@ namespace crepe {
 
 class Script;
 
+/**
+ * \brief Script system
+ * 
+ * The script system is responsible for all \c BehaviorScript components, and
+ * calls the methods on classes derived from \c Script.
+ */
 class ScriptSystem : public System {
 public:
+	/**
+	 * \brief Call Script::update() on all active \c BehaviorScript instances
+	 *
+	 * This routine updates all scripts sequentially using the Script::update()
+	 * method. It also calls Script::init() if this has not been done before on
+	 * the \c BehaviorScript instance.
+	 */
 	void update();
 
 private:
 	// TODO: to forward_list<reference_wrapper>
+	/**
+	 * \brief Aggregate all active \c BehaviorScript components and return a list
+	 * of references to their \c Script instances (utility)
+	 *
+	 * \returns List of active \c Script instances
+	 */
 	std::forward_list<Script *> get_scripts() const;
 };
 
diff --git a/src/crepe/system/System.h b/src/crepe/system/System.h
index 3b81bef..ec4507f 100644
--- a/src/crepe/system/System.h
+++ b/src/crepe/system/System.h
@@ -2,8 +2,18 @@
 
 namespace crepe {
 
+/**
+ * \brief Base ECS system class
+ *
+ * This class is used as the base for all system classes. Classes derived from
+ * System must implement the System::update() method and copy Script::Script
+ * with the `using`-syntax.
+ */
 class System {
 public:
+	/**
+	 * \brief Process all components this system is responsible for.
+	 */
 	virtual void update() = 0;
 
 public:
diff --git a/src/example/audio_internal.cpp b/src/example/audio_internal.cpp
index 1ea839d..ff55a59 100644
--- a/src/example/audio_internal.cpp
+++ b/src/example/audio_internal.cpp
@@ -5,7 +5,7 @@
 
 #include <crepe/api/Config.h>
 #include <crepe/facade/Sound.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 #include <thread>
 
@@ -18,7 +18,7 @@ using std::make_unique;
 int _ = []() {
 	// Show dbg_trace() output
 	auto & cfg = Config::get_instance();
-	cfg.log.level = LogLevel::TRACE;
+	cfg.log.level = Log::Level::TRACE;
 
 	return 0; // satisfy compiler
 }();
diff --git a/src/example/components_internal.cpp b/src/example/components_internal.cpp
index ea1eaad..f7e395b 100644
--- a/src/example/components_internal.cpp
+++ b/src/example/components_internal.cpp
@@ -13,7 +13,7 @@
 #include <crepe/api/Rigidbody.h>
 #include <crepe/api/Sprite.h>
 
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 using namespace crepe;
 using namespace std;
diff --git a/src/example/db.cpp b/src/example/db.cpp
index 8c06a84..ee4e8fc 100644
--- a/src/example/db.cpp
+++ b/src/example/db.cpp
@@ -1,6 +1,6 @@
 #include <crepe/api/Config.h>
 #include <crepe/facade/DB.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 using namespace crepe;
 using namespace std;
@@ -8,7 +8,7 @@ using namespace std;
 // run before main
 static auto _ = []() {
 	auto & cfg = Config::get_instance();
-	cfg.log.level = LogLevel::TRACE;
+	cfg.log.level = Log::Level::TRACE;
 	return 0;
 }();
 
@@ -20,11 +20,11 @@ int main() {
 	const char * test_key = "test-key";
 	string test_data = "Hello world!";
 
-	dbg_logf("DB has key = %d", db.has(test_key));
+	dbg_logf("DB has key = {}", db.has(test_key));
 
 	db.set(test_key, test_data);
 
-	dbg_logf("key = \"%s\"", db.get(test_key).c_str());
+	dbg_logf("key = \"{}\"", db.get(test_key));
 
 	return 0;
 }
diff --git a/src/example/proxy.cpp b/src/example/proxy.cpp
index 0afff41..ca68d9a 100644
--- a/src/example/proxy.cpp
+++ b/src/example/proxy.cpp
@@ -6,7 +6,7 @@
 #include <crepe/ValueBroker.h>
 #include <crepe/api/Config.h>
 #include <crepe/util/Proxy.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 using namespace std;
 using namespace crepe;
@@ -17,18 +17,17 @@ void test_ro_val(int val) {}
 
 int main() {
 	auto & cfg = Config::get_instance();
-	cfg.log.level = LogLevel::DEBUG;
+	cfg.log.level = Log::Level::DEBUG;
 
 	int real_value = 0;
 
 	ValueBroker<int> broker{
 		[&real_value](const int & target) {
-			dbg_logf("set %s to %s", to_string(real_value).c_str(),
-					 to_string(target).c_str());
+			dbg_logf("set {} to {}", real_value, target);
 			real_value = target;
 		},
 		[&real_value]() -> const int & {
-			dbg_logf("get %s", to_string(real_value).c_str());
+			dbg_logf("get {}", real_value);
 			return real_value;
 		},
 	};
diff --git a/src/example/rendering.cpp b/src/example/rendering.cpp
index d554a8a..cbd7de7 100644
--- a/src/example/rendering.cpp
+++ b/src/example/rendering.cpp
@@ -1,7 +1,7 @@
 #include <crepe/ComponentManager.h>
 #include <crepe/api/GameObject.h>
 #include <crepe/system/RenderSystem.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 #include <crepe/api/AssetManager.h>
 #include <crepe/api/Color.h>
diff --git a/src/example/savemgr.cpp b/src/example/savemgr.cpp
index 436fb5a..5a415b7 100644
--- a/src/example/savemgr.cpp
+++ b/src/example/savemgr.cpp
@@ -7,7 +7,7 @@
 #include <crepe/api/Config.h>
 #include <crepe/api/SaveManager.h>
 #include <crepe/util/Proxy.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 using namespace crepe;
 
@@ -15,7 +15,7 @@ using namespace crepe;
 int _ = []() {
 	// make sure all log messages get printed
 	auto & cfg = Config::get_instance();
-	cfg.log.level = LogLevel::TRACE;
+	cfg.log.level = Log::Level::TRACE;
 
 	return 0; // satisfy compiler
 }();
@@ -25,19 +25,19 @@ int main() {
 
 	SaveManager & mgr = SaveManager::get_instance();
 
-	dbg_logf("has key = %s", mgr.has(key) ? "true" : "false");
+	dbg_logf("has key = {}", mgr.has(key));
 	ValueBroker<int> prop = mgr.get<int>(key, 0);
 	Proxy<int> val = mgr.get<int>(key, 0);
 
-	dbg_logf("val = %d", mgr.get<int>(key).get());
+	dbg_logf("val = {}", mgr.get<int>(key).get());
 	prop.set(1);
-	dbg_logf("val = %d", mgr.get<int>(key).get());
+	dbg_logf("val = {}", mgr.get<int>(key).get());
 	val = 2;
-	dbg_logf("val = %d", mgr.get<int>(key).get());
+	dbg_logf("val = {}", mgr.get<int>(key).get());
 	mgr.set<int>(key, 3);
-	dbg_logf("val = %d", mgr.get<int>(key).get());
+	dbg_logf("val = {}", mgr.get<int>(key).get());
 
-	dbg_logf("has key = %s", mgr.has(key) ? "true" : "false");
+	dbg_logf("has key = {}", mgr.has(key));
 	assert(true == mgr.has(key));
 
 	return 0;
diff --git a/src/example/script.cpp b/src/example/script.cpp
index 9e8b147..d1388b5 100644
--- a/src/example/script.cpp
+++ b/src/example/script.cpp
@@ -5,7 +5,7 @@
 
 #include <crepe/ComponentManager.h>
 #include <crepe/system/ScriptSystem.h>
-#include <crepe/util/log.h>
+#include <crepe/util/Log.h>
 
 #include <crepe/api/BehaviorScript.h>
 #include <crepe/api/Config.h>
@@ -20,7 +20,7 @@ using namespace std;
 int _ = []() {
 	// Show dbg_trace() output
 	auto & cfg = Config::get_instance();
-	cfg.log.level = LogLevel::TRACE;
+	cfg.log.level = Log::Level::TRACE;
 
 	return 0; // satisfy compiler
 }();
@@ -30,7 +30,7 @@ class MyScript : public Script {
 	void update() {
 		// Retrieve component from the same GameObject this script is on
 		Transform & test = get_component<Transform>();
-		dbg_logf("Transform(%.2f, %.2f)", test.position.x, test.position.y);
+		dbg_logf("Transform({:.2f}, {:.2f})", test.position.x, test.position.y);
 	}
 };
 
-- 
cgit v1.2.3