docs(core): add FieldsTrait sample

core/samples/CMakeLists.txt

@@ -29,6 +29,7 @@ endmacro()
 make_sample(DIR "logging")
 make_sample(DIR "reflection/basic")
 make_sample(DIR "reflection/traits/constructible")
+make_sample(DIR "reflection/traits/fields")
 make_sample(DIR "data/fs/embedded_archive" SOURCES "embed.cpp")
 make_sample(DIR "data/fs/standard_archive")
 make_sample(DIR "data/serialization")

core/samples/reflection/page.md

@@ -4,3 +4,4 @@
 
 - @subpage examples-core-reflection-basic - @copybrief examples-core-reflection-basic
 - @subpage examples-core-reflection-traits-constructible - @copybrief examples-core-reflection-traits-constructible
+- @subpage examples-core-reflection-traits-fields - @copybrief examples-core-reflection-traits-fields

core/samples/reflection/traits/fields/main.cpp

@@ -0,0 +1,54 @@
+#include <cubos/core/log.hpp>
+
+/// [Person declaration]
+#include <cubos/core/reflection/reflect.hpp>
+
+struct Person
+{
+    CUBOS_REFLECT;
+    int age;
+    float weight;
+};
+/// [Person declaration]
+
+/// [Reflection definition]
+#include <cubos/core/reflection/traits/fields.hpp>
+#include <cubos/core/reflection/type.hpp>
+
+// Since we're exposing fields of primitive types (int and float), its important to include the
+// header which defines their reflection.
+#include <cubos/core/reflection/external/primitives.hpp>
+
+using cubos::core::reflection::FieldsTrait;
+using cubos::core::reflection::Type;
+
+CUBOS_REFLECT_IMPL(Person)
+{
+    return Type::create("Person").with(
+        FieldsTrait().withField("age", &Person::age).withField("weight", &Person::weight));
+}
+/// [Reflection definition]
+
+/// [Accessing the trait]
+int main()
+{
+    using cubos::core::reflection::reflect;
+
+    const auto& personType = reflect<Person>();
+    CUBOS_ASSERT(personType.has<FieldsTrait>());
+    const auto& fields = personType.get<FieldsTrait>();
+    /// [Accessing the trait]
+
+    /// [Iterating over fields]
+    for (auto field = fields.firstField(); field != nullptr; field = field->next())
+    {
+        CUBOS_INFO("Field '{}' of type '{}'", field->name(), field->type().name());
+    }
+    /// [Iterating over fields]
+
+    /// [Accessing fields by name]
+    Person person{.age = 21, .weight = 68.4F};
+    *static_cast<float*>(fields.field("weight")->pointerTo(&person)) += 20.0F;
+    CUBOS_INFO("New weight: {}", person.weight); // 88.4
+}
+/// [Accessing fields by name]

core/samples/reflection/traits/fields/page.md

@@ -0,0 +1,31 @@
+# Fields Trait {#examples-core-reflection-traits-fields}
+
+@brief Exposing the fields of a type.
+
+For structured types, like classes and structs, you might want to expose its
+public fields using the @ref cubos::core::reflection::FieldsTrait "FieldsTrait"
+trait. In this example, we'll expose the fields of the following type:
+
+@snippet reflection/traits/fields/main.cpp Person declaration
+
+In its reflection definition, we'll add the @ref
+cubos::core::reflection::FieldsTrait "FieldsTrait" trait to it with each of the
+fields we want to expose:
+
+@snippet reflection/traits/fields/main.cpp Reflection definition
+
+@note Make you sure you include the reflection declarations for the types of
+the fields you expose! In this case, we need the @ref
+core/reflection/external/primitives.hpp header.
+
+Accessing this trait is the same as with any other trait:
+
+@snippet reflection/traits/fields/main.cpp Accessing the trait
+
+We can iterate over the fields of the type with it:
+
+@snippet reflection/traits/fields/main.cpp Iterating over fields
+
+Its also possible to access the fields by name:
+
+@snippet reflection/traits/fields/main.cpp Accessing fields by name