docs: overhaul introduction and other pages

Restructures the whole documentation pages.
Replace old structure pages by in-code documentation.
Revamp old ECS and Cubinhos guides, add plugins guide.
Add logging example.

core/include/cubos/core/ecs/blueprint.hpp

@@ -14,7 +14,7 @@
 namespace cubos::core::ecs
 {
     /// @brief Stores a bundle of entities and their respective components, which can be easily
-    /// spawned into a world. This is in a way the 'Prefab' of CUBOS., but lower level.
+    /// spawned into a world. This is in a way the 'Prefab' of @b CUBOS., but lower level.
     class Blueprint final
     {
     public:

core/include/cubos/core/ecs/module.dox

@@ -25,8 +25,8 @@ namespace cubos::core::ecs
     /// bit of a mess. Most of the exposed types are internal to the documentation, and thus it can
     /// get hard to navigate (TODO #377).
     ///
-    /// @note Check out the @ref guide-ecs "ECS guide" for a more in-depth explanation of this
-    /// module.
+    /// @note Check out the @ref features-ecs "ECS feature guide" for an in-depth explanation of
+    /// what an ECS is and how it can be used.
     ///
     /// ## Data types
     /// - @ref World - stores entities, components and resources, can be queried.
@@ -35,16 +35,22 @@ namespace cubos::core::ecs
     ///   Commands.
     ///
     /// ## System argument types
-    /// - @ref Read - used to read resource data.
-    /// - @ref Write - used to write resource data.
+    /// - @ref Read "Read<R>" - used to read resource data of type @p R.
+    /// - @ref Write "Write<R>" - used to write resource data of type @p R.
+    /// - @ref Read "Read<World>" - used to read the world directly (not recommended, ruins
+    ///   parallelism, prefer @ref Commands).
+    /// - @ref Write "Write<World>" - used to write the world directly (not recommended, ruins
+    ///   parallelism, prefer @ref Commands).
     /// - @ref Commands - used to queue entities to be created, destroyed and other operations.
-    /// - @ref EventReader - used to read events sent from other systems.
-    /// - @ref EventWriter - used to send events to other systems.
-    /// - @ref Query - used to query the world for entities with certain components.
+    /// - @ref EventReader "EventReader<E>" - reads events of type @p E sent from other systems.
+    /// - @ref EventWriter "EventWriter<E>" - sends events of type @p E to other systems.
+    /// - @ref Query "Query<Args...>" - queries the world for entities which match its arguments.
     ///
     /// ## Query argument types
-    /// - @ref Read - matches entities with the specified component, read-only access.
-    /// - @ref Write - matches entities with the specified component, write access.
-    /// - @ref OptRead - matches all entities, read-only access when the component is present.
-    /// - @ref OptWrite - matches all entities, write access when the component is present.
+    /// - @ref Read "Read<C>" - matches entities with the component @p C, read-only access.
+    /// - @ref Write "Write<C>" - matches entities with the component @p C, write access.
+    /// - @ref OptRead "OptRead<C>" - matches all entities, read-only access when the component
+    ///   @p C is present.
+    /// - @ref OptWrite "OptWrite<C>" - matches all entities, write access when the component
+    ///   @p C is present.
 }

core/include/cubos/core/ecs/system.hpp

@@ -106,6 +106,32 @@ namespace cubos::core::ecs
         {
             // This should never be instantiated.
             static_assert(!std::is_same_v<T, T>, "Unknown system argument type.");
+
+            // Placeholders for documentation.
+
+            using Type = void; ///< Type of the fetched data.
+            using State = void;
+
+            /// @brief Adds the argument @p T to the given @p info.
+            /// @param[out] info System information.
+            static void add(SystemInfo& info);
+
+            /// @brief Prepares the argument for being executed on the given @p world.
+            /// @param world World to prepare the argument for.
+            /// @return State of the argument.
+            static State prepare(World& world);
+
+            /// @brief Fetches the data from the given @p world.
+            /// @param world World to fetch the data from.
+            /// @param commands Buffer where commands can be submitted to.
+            /// @param state State of the argument.
+            /// @return Fetched data.
+            static Type fetch(World& world, CommandBuffer& commands, State& state);
+
+            /// @brief Converts the fetched data into the actual desired argument.
+            /// @param fetched Fetched data.
+            /// @return Actual argument.
+            static T arg(Type&& fetched);
         };
 
         template <typename R>

core/include/cubos/core/gl/grid.hpp

@@ -26,6 +26,7 @@ namespace cubos::core::data
 namespace cubos::core::gl
 {
     /// @brief Represents a voxel object using a 3D grid.
+    /// @see Each voxel stores a material index to be used with a @ref Palette.
     /// @ingroup core-gl
     class Grid final
     {

core/include/cubos/core/gl/palette.hpp

@@ -22,6 +22,15 @@ namespace cubos::core::data
 namespace cubos::core::gl
 {
     /// @brief Holds a palette of materials. Supports up to 65535 materials.
+    ///
+    /// Instead of storing the materials themselves in voxel data, @b CUBOS.
+    /// uses palettes, and stores the index of the material in the palette
+    /// instead.
+    ///
+    /// This allows for more efficient storage of voxel data, since now instead
+    /// of storing the whole material per each voxel, we just store a 16-bit
+    /// integer.
+    ///
     /// @ingroup core-gl
     class Palette final
     {

core/include/cubos/core/gl/render_device.hpp

@@ -706,6 +706,11 @@ namespace cubos::core::gl
     };
 
     /// @brief Interface used to wrap low-level rendering APIs such as OpenGL.
+    ///
+    /// Using this interface, the engine never directly interacts with *OpenGL* or any other
+    /// low-level rendering API. This allows use to use different rendering APIs without having
+    /// to change the engine code, which is useful for porting the engine to different platforms.
+    ///
     /// @see @ref io::Window is responsible for creating a render device for itself.
     /// @ingroup core-gl
     class RenderDevice

core/include/cubos/core/io/window.hpp

@@ -119,6 +119,7 @@ namespace cubos::core::io
                                      ResizeEvent, TextEvent>;
 
     /// @brief Handle to a window.
+    /// @see @ref BaseWindow @copybrief BaseWindow
     /// @ingroup core-io
     using Window = std::shared_ptr<BaseWindow>;
 
@@ -131,7 +132,8 @@ namespace cubos::core::io
 
     /// @brief Interface used to wrap low-level window API implementations.
     ///
-    /// Handles input events and creates a @ref gl::RenderDevice.
+    /// Allows polling of input events and creates a @ref gl::RenderDevice for rendering to the
+    /// window.
     ///
     /// @ingroup core-io
     class BaseWindow

core/include/cubos/core/memory/module.dox

@@ -11,5 +11,5 @@ namespace cubos::core::memory
 {
     /// @defgroup core-memory Memory
     /// @ingroup core
-    /// @brief Provides memory utilities.
+    /// @brief Provides a stream library and memory utilities.
 } // namespace cubos::core::memory

core/include/cubos/core/memory/stream.hpp

@@ -20,6 +20,14 @@ namespace cubos::core::memory
     };
 
     /// @brief Interface class for memory streams. Abstracts away sources or destinations of data.
+    ///
+    /// ## Motivation
+    ///
+    /// Why do we have our own streams? Well, the standard library streams are hard to use and
+    /// extend, and very template heavy. Using our own streams allows us to abstract away more
+    /// easily where the data is coming from, or going to, allowing us, for example, to embed
+    /// files into the executable and not have to worry about the code that reads them.
+    ///
     /// @ingroup core-memory
     class Stream
     {

core/include/cubos/core/module.dox

@@ -1,16 +1,20 @@
 /// @dir
-/// @brief @ref cubos::core namespace.
+/// @brief @ref core module.
 
 #pragma once
 
 /// @namespace cubos::core
-/// @brief CUBOS. core namespace.
+/// @brief @ref core namespace.
 
 namespace cubos::core
 {
     /// @defgroup core Core
-    /// @brief CUBOS. core library.
+    /// @brief @b CUBOS. core library.
     ///
-    /// The core library contains loose utilities and functionality on which the rest of the CUBOS.
-    /// libraries are built on.
-}
+    /// The core library contains loose utilities and functionality on which the rest of the
+    /// @b CUBOS. libraries and applications are built on. Lives in the @ref cubos::core namespace.
+    ///
+    /// This library can be further divided into modules, which are documented in their respective
+    /// module pages. Each of these modules has its own namespace and directory in the source tree.
+    /// For example, the @ref core-ecs module lives in the @ref cubos::core::ecs namespace.
+} // namespace cubos::core

core/include/cubos/core/ui/imgui.hpp

@@ -21,7 +21,8 @@ namespace cubos::core::ui
     /// @ingroup core-ui
     void terminate();
 
-    /// @brief Begins a new ImGui frame.
+    /// @brief Begins a new ImGui frame. ImGui calls should be made between this and @ref
+    /// endFrame().
     /// @ingroup core-ui
     void beginFrame();
 

core/include/cubos/core/ui/module.dox

@@ -12,4 +12,7 @@ namespace cubos::core::ui
     /// @defgroup core-ui User Interface
     /// @ingroup core
     /// @brief Provides `ImGui` integration and general UI utilities.
+    ///
+    /// @note @b CUBOS. UI support is built on top of
+    /// [*Dear ImGui*](https://github.com/ocornut/imgui).
 } // namespace cubos::core::ui

core/samples/data/fs/embedded_archive/main.cpp

@@ -1,7 +1,7 @@
 /// @file
 /// @brief Sample which showcases how the EmbeddedArchive class can be used.
 ///
-/// @details The `assets` directory on the same directory as this file was embedded into
+/// The `assets` directory on the same directory as this file was embedded into
 /// `embed.cpp` using the command `cubinhos embed -r assets > embed.cpp`. Since no further options
 /// were specified, `cubinhos` registered the data with the name of the embedded file - `assets`.
 

core/samples/logging.cpp

@@ -1,27 +1,40 @@
 #include <glm/glm.hpp>
 
-#include <cubos/core/data/debug_serializer.hpp>
+/// [Logging include]
 #include <cubos/core/log.hpp>
-#include <cubos/core/memory/buffer_stream.hpp>
+/// [Logging include]
+
+/// [Debug wrapper include]
+#include <cubos/core/data/debug_serializer.hpp>
 
-using namespace cubos::core;
 using data::Debug;
+/// [Debug wrapper include]
 
+#include <cubos/core/memory/buffer_stream.hpp>
+
+/// [Logger initialization]
 int main()
 {
-    initializeLogger();
+    cubos::core::initializeLogger();
+    /// [Logger initialization]
 
+    /// [Logging macros]
     CUBOS_TRACE("Trace message");
     CUBOS_DEBUG("Debug message");
     CUBOS_INFO("Info message");
     CUBOS_WARN("Warning message");
     CUBOS_ERROR("Error message");
     CUBOS_CRITICAL("Critical message");
+    /// [Logging macros]
 
+    /// [Logging macros with arguments]
+    CUBOS_ERROR("Error message with {} argument", 1);
+    /// [Logging macros with arguments]
+
+    /// [Debug wrapper usage]
     CUBOS_INFO("Serializable type: {}", Debug(glm::vec3(0.0F, 1.0F, 2.0F)));
     CUBOS_INFO("Again, but with type information: {:t}", Debug(glm::vec3(0.0F, 1.0F, 2.0F)));
     CUBOS_INFO("Since unordered maps are serializable, we can do this: {}",
                Debug((std::unordered_map<int, const char*>{{1, "one"}, {2, "two"}})));
-
-    return 0;
 }
+/// [Debug wrapper usage]

docs/Doxyfile

@@ -3,19 +3,46 @@ PROJECT_NAME = @DOXYGEN_PROJECT_NAME@
 PROJECT_NUMBER = @DOXYGEN_PROJECT_VERSION@
 
 # Add sources
-INPUT = @DOXYGEN_PROJECT_ROOT@/docs/pages @DOXYGEN_PROJECT_ROOT@/core/include @DOXYGEN_PROJECT_ROOT@/engine/include
+INPUT = @DOXYGEN_PROJECT_ROOT@/docs/pages \
+        @DOXYGEN_PROJECT_ROOT@/core/include \
+        @DOXYGEN_PROJECT_ROOT@/engine/include
+EXAMPLE_PATH = @DOXYGEN_PROJECT_ROOT@/core/samples \
+               @DOXYGEN_PROJECT_ROOT@/engine/samples
 EXTRACT_ALL = YES
+EXTRACT_PRIVATE = YES
+EXTRACT_PRIV_VIRTUAL = YES
 RECURSIVE = YES
 OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@
 IMAGE_PATH = @DOXYGEN_PROJECT_ROOT@/docs/images
 
 # Use relative include paths
 FULL_PATH_NAMES = YES
-STRIP_FROM_PATH = @DOXYGEN_PROJECT_ROOT@/core/include/cubos @DOXYGEN_PROJECT_ROOT@/engine/include/cubos @DOXYGEN_PROJECT_ROOT@
+STRIP_FROM_PATH = @DOXYGEN_PROJECT_ROOT@/core/include/cubos \
+                  @DOXYGEN_PROJECT_ROOT@/core/samples \
+                  @DOXYGEN_PROJECT_ROOT@/engine/include/cubos \
+                  @DOXYGEN_PROJECT_ROOT@/engine/samples \
+                  @DOXYGEN_PROJECT_ROOT@
 
 # We use m.css to generate the html documentation, so we only need XML output
 GENERATE_XML = YES
 GENERATE_HTML = NO
 GENERATE_LATEX = NO
 XML_PROGRAMLISTING = NO
+XML_NS_MEMB_FILE_SCOPE = YES
 CREATE_SUBDIRS = NO
+
+# We do not want a todo list
+GENERATE_TODOLIST = NO
+
+# Add some useful aliases
+ALIASES += \
+    "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
+    "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
+    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
+    "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
+    "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
+    "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
+    "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
+    "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly"