docs(core): add core-sample.reflection

core/samples/CMakeLists.txt

@@ -29,6 +29,7 @@ endmacro()
 # Set sample source files
 set(CORE_SAMPLES_SOURCES
     "logging.cpp"
+    "reflection.cpp"
     "render_device.cpp"
     "render_device_compute.cpp"
     "debug_renderer.cpp"

core/samples/reflection.cpp

@@ -0,0 +1,69 @@
+#include <cubos/core/log.hpp>
+
+/// [Person definition]
+#include <cubos/core/reflection/reflect.hpp>
+
+struct Person
+{
+    CUBOS_REFLECT;
+    int age;
+    float weight;
+};
+/// [Person definition]
+
+/// [Person reflection]
+#include <cubos/core/reflection/type.hpp>
+
+using cubos::core::reflection::Type;
+
+CUBOS_REFLECT_IMPL(Person)
+{
+    return Type::create("Person");
+}
+/// [Person reflection]
+
+/// [Position definition]
+struct Position
+{
+    CUBOS_REFLECT;
+    float x, y;
+};
+/// [Position definition]
+
+/// [Your own trait]
+struct ColorTrait
+{
+    float r, g, b;
+};
+/// [Your own trait]
+
+/// [Adding your own trait]
+CUBOS_REFLECT_IMPL(Position)
+{
+    return Type::create("Position").with(ColorTrait{.r = 0.0F, .g = 1.0F, .b = 0.0F});
+}
+/// [Adding your own trait]
+
+/// [Accessing type name]
+int main()
+{
+    using cubos::core::reflection::reflect;
+
+    const auto& personType = reflect<Person>();
+    CUBOS_ASSERT(personType.name() == "Person");
+    /// [Accessing type name]
+
+    /// [Checking traits]
+    const auto& positionType = reflect<Position>();
+    CUBOS_ASSERT(positionType.has<ColorTrait>());
+    CUBOS_ASSERT(!personType.has<ColorTrait>());
+    /// [Checking traits]
+
+    /// [Accessing traits]
+    const auto& colorTrait = positionType.get<ColorTrait>();
+    CUBOS_ASSERT(colorTrait.r == 0.0F);
+    CUBOS_ASSERT(colorTrait.g == 1.0F);
+    CUBOS_ASSERT(colorTrait.b == 0.0F);
+    return 0;
+}
+/// [Accessing traits]

docs/pages/3_examples/1_core/2_reflection.md

@@ -0,0 +1,47 @@
+# Reflection {#examples-core-reflection}
+
+@brief Using the reflection system.
+
+Lets say you have a type `Person`, which you want to be able to reflect. You
+can declare it as reflectable using the macro @ref CUBOS_REFLECT, for example,
+in your header, like this:
+
+@snippet reflection.cpp Person definition
+
+The @ref core/reflection/reflect.hpp is a very lightweight header, and thus you
+should avoid including any other reflection headers in your headers whenever
+possible, in order to reduce compile times.
+
+In your source file, you must define the reflection data for your type. This is
+done through the @ref CUBOS_REFLECT_IMPL macro:
+
+@snippet reflection.cpp Person reflection
+
+To access this reflection data, you should use the
+@ref cubos::core::reflection::reflect function, which is also defined in the
+@ref core/reflection/reflect.hpp header.
+
+@snippet reflection.cpp Accessing type name
+
+Lets say you want to associate your own data to your types, to describe them
+further. For example, imagine you're making a GUI editor for your game and you
+which to display the fields of your types in a tree view, with different colors
+for different types. You could associate colors to your types by defining a
+trait:
+
+@snippet reflection.cpp Your own trait
+
+Now, when you define your type reflection, you add your trait with the
+@ref cubos::core::reflection::Type::with "Type::with" method.
+
+@snippet reflection.cpp Adding your own trait
+
+To check if a type has a trait, you use the
+@ref cubos::core::reflection::Type::has "Type::has" method.
+
+@snippet reflection.cpp Checking traits
+
+To actually access the trait data, you use the
+@ref cubos::core::reflection::Type::get "Type::get" method.
+
+@snippet reflection.cpp Accessing traits

docs/pages/3_examples/1_core/main.md

@@ -10,6 +10,7 @@ will need to use some of the features of the @ref core library directly.
 
 The following examples have fully documented tutorials:
 - @subpage examples-core-logging - @copybrief examples-core-logging
+- @subpage examples-core-reflection - @copybrief examples-core-reflection
 
 ## Undocumented examples