more documentation

9 files changed, 137 insertions, 10 deletions

diff --git a/contributing.md b/contributing.md
index 77a2908..0a90e86 100644
--- a/contributing.md
+++ b/contributing.md
@@ -17,6 +17,7 @@ that you can click on to open them.
   working/compiling version of the project
 - Pull requests for new code include either automated tests for the new code or
   an explanation as to why the code can not (reliably) be tested
+
 <!--
 - TODO: tagging / versions
 -->
@@ -495,6 +496,12 @@ that you can click on to open them.
   </td></tr></table></details>
 - <details><summary>
   Ensure const-correctness
+
+  > [!IMPORTANT]
+  > C-style APIs that work on (possibly internal) references to structs can be
+  > called from const member functions in C++. If the compiler allows you to
+  > mark a function as `const` even though it has side effects, it should
+  > **not** be marked as `const`.
   </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
@@ -795,6 +802,23 @@ that you can click on to open them.
   ```
   </td></tr></table></details>
 - Do not implement new classes as singletons
+- <details><summary>
+  Retrieving the first or last indices for iterators with a known or expected
+  size should be done using <code>.front()</code> or <code>.back()</code>
+  instead of by index
+  </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td>
+
+  ```cpp
+  vector<int> foo = { 1, 2, 3 };
+  int bar = foo.first();
+  ```
+  </td><td>
+
+  ```cpp
+  vector<int> foo = { 1, 2, 3 };
+  int bar = foo[0];
+  ```
+  </td></tr></table></details>
 
 ## CMakeLists-specific
 
diff --git a/src/crepe/api/Script.h b/src/crepe/api/Script.h
index f0b9c73..a0870cb 100644
--- a/src/crepe/api/Script.h
+++ b/src/crepe/api/Script.h
@@ -22,6 +22,10 @@ class ComponentManager;
  * \info Additional *events* (like Unity's OnDisable and OnEnable) should be implemented as
  * member or lambda methods in derivative user script classes and registered in \c init().
  *
+ * \warning Concrete scripts are allowed do create a custom constructor, but the utility
+ * functions should not be called inside the constructor as they rely on late references that
+ * are only available after the constructor returns.
+ *
  * \see feature_script
  */
 class Script {
@@ -63,8 +67,7 @@ protected:
 	 *
 	 * \returns Reference to component
 	 *
-	 * \throws std::runtime_error if this game object does not have a component matching type \c
-	 * T
+	 * \throws std::runtime_error if this game object does not have a component with type \c T
 	 */
 	template <typename T>
 	T & get_component() const;
diff --git a/src/doc/internal/component.dox b/src/doc/internal/component.dox
new file mode 100644
index 0000000..0dd4cb5
--- /dev/null
+++ b/src/doc/internal/component.dox
@@ -0,0 +1,41 @@
+// vim:ft=doxygen
+namespace crepe {
+/**
+
+\defgroup internal_component Components
+\ingroup internal
+\brief ECS Components
+
+Components are attached to GameObject instances and are composed by the game
+programmer to create specific entities in the game world. While they are
+implemented as C++ classes, components should be treated as C-style structs,
+meaning all members are public and they do not contain functions.
+
+A basic component has the following structure:
+```cpp
+#include <crepe/Component.h>
+
+class MyComponent : public crepe::Component {
+public:
+	// Add your custom component's ininitializer properties after the `id`
+	// parameter. The first parameter is controlled by GameObject::add_component,
+	// while all other parameters are forwarded using std::forward.
+	MyComponent(game_object_id_t id, ...);
+
+	// Optionally define the `get_instances_max` method to limit the amount of
+	// instances of this component per GameObject. The default implementation for
+	// this function returns -1, which means the instance count does not have an
+	// upper limit:
+	virtual int get_instances_max() const { return -1; }
+
+	// Properties
+	// ...
+};
+```
+
+Generally, components are "handled" by \ref internal_system "systems", which may
+optionally change the components' state. Components' state may also be
+controlled by the game programmer through \ref feature_script "scripts".
+
+*/
+}
diff --git a/src/doc/internal/resource.dox b/src/doc/internal/resource.dox
new file mode 100644
index 0000000..56f1de0
--- /dev/null
+++ b/src/doc/internal/resource.dox
@@ -0,0 +1,12 @@
+// vim:ft=doxygen
+namespace crepe {
+/**
+
+\defgroup internal_resource Resources
+\ingroup internal
+\brief Concrete resources
+
+\todo This section is incomplete
+
+*/
+}
diff --git a/src/doc/internal/style.dox b/src/doc/internal/style.dox
new file mode 100644
index 0000000..dad2df0
--- /dev/null
+++ b/src/doc/internal/style.dox
@@ -0,0 +1,9 @@
+// vim:ft=doxygen
+/**
+
+\defgroup internal_style Code style
+\ingroup internal
+\brief Coding conventions
+\include{doc} contributing.md
+
+*/
diff --git a/src/doc/internal/system.dox b/src/doc/internal/system.dox
new file mode 100644
index 0000000..17a101e
--- /dev/null
+++ b/src/doc/internal/system.dox
@@ -0,0 +1,26 @@
+// vim:ft=doxygen
+namespace crepe {
+/**
+
+\defgroup internal_system Systems
+\ingroup internal
+\brief ECS Systems
+
+\todo This section is incomplete
+
+A system is responsible for processing the data stored in \ref
+internal_component "components".
+
+A basic system has the following structure:
+```cpp
+#include <crepe/system/System.h>
+
+class MySystem : public System {
+public:
+	using System::System;
+	void update() override;
+};
+```
+
+*/
+}
diff --git a/src/doc/internals.dox b/src/doc/internals.dox
new file mode 100644
index 0000000..2d2ca56
--- /dev/null
+++ b/src/doc/internals.dox
@@ -0,0 +1,10 @@
+// vim:ft=doxygen
+/**
+
+\defgroup internal Internals
+\brief Internal engine structure and other conventions
+
+\todo This page is incomplete
+\todo Anything about Contexts?
+
+*/
diff --git a/src/doc/layout.xml b/src/doc/layout.xml
index 6bde443..fb4cc0c 100644
--- a/src/doc/layout.xml
+++ b/src/doc/layout.xml
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <doxygenlayout version="1.0">
 	<navindex>
-		<tab type="mainpage" visible="yes" title=""/>
+		<tab type="mainpage" visible="yes" title="Intro"/>
 		<tab type="user" url="@ref install" title="Installation"/>
 		<tab type="user" url="@ref feature" title="Features"/>
 		<tab type="user" url="@ref internal" title="Internals"/>
 		<tab type="pages" visible="no" title="" intro=""/>
 		<tab type="topics" visible="no" title="" intro=""/>
-		<tab type="modules" visible="yes" title="" intro="">
+		<tab type="modules" visible="no" title="" intro="">
 			<tab type="modulelist" visible="yes" title="" intro=""/>
 			<tab type="modulemembers" visible="yes" title="" intro=""/>
 		</tab>
@@ -15,9 +15,9 @@
 			<tab type="namespacelist" visible="yes" title="" intro=""/>
 			<tab type="namespacemembers" visible="yes" title="" intro=""/>
 		</tab>
-		<tab type="concepts" visible="yes" title="">
+		<tab type="concepts" visible="no" title="">
 		</tab>
-		<tab type="interfaces" visible="yes" title="">
+		<tab type="interfaces" visible="no" title="">
 			<tab type="interfacelist" visible="yes" title="" intro=""/>
 			<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
 			<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
@@ -28,20 +28,20 @@
 			<tab type="hierarchy" visible="yes" title="" intro=""/>
 			<tab type="classmembers" visible="yes" title="" intro=""/>
 		</tab>
-		<tab type="structs" visible="yes" title="">
+		<tab type="structs" visible="no" title="">
 			<tab type="structlist" visible="yes" title="" intro=""/>
 			<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
 		</tab>
-		<tab type="exceptions" visible="yes" title="">
+		<tab type="exceptions" visible="no" title="">
 			<tab type="exceptionlist" visible="yes" title="" intro=""/>
 			<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
 			<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
 		</tab>
-		<tab type="files" visible="yes" title="">
+		<tab type="files" visible="no" title="">
 			<tab type="filelist" visible="yes" title="" intro=""/>
 			<tab type="globals" visible="yes" title="" intro=""/>
 		</tab>
-		<tab type="examples" visible="yes" title="" intro=""/>
+		<tab type="examples" visible="no" title="" intro=""/>
 	</navindex>
 	<class>
 		<briefdescription visible="yes"/>
diff --git a/src/doc/style.css b/src/doc/style.css
index 08bc9f5..daabd39 100644
--- a/src/doc/style.css
+++ b/src/doc/style.css
@@ -2,3 +2,5 @@
 address {
 	display: none;
 }
+
+h2.groupheader { margin-top: revert; }