Added more comments

Author: liuzicheng1987

include/rfl/Commented.hpp

@@ -10,18 +10,20 @@
 
 namespace rfl {
 
-/// Wraps a field value with an optional comment for formats that support comments.
-/// The comment is preserved during serialization and deserialization for formats like TOML and YAML
-/// that support inline comments. For formats without comment support, the comment is ignored.
-/// This allows you to maintain documentation/metadata alongside your data.
+/// Wraps a field value with an optional comment for formats that support
+/// comments. The comment is preserved during serialization for formats like
+/// TOML and YAML that support inline comments. For formats without comment
+/// support, the comment is ignored. This allows you to maintain
+/// documentation/metadata alongside your data.
 /// @tparam T The type of the field value
 template <class T>
 struct Commented {
  public:
   using Type = std::remove_cvref_t<T>;
   using ReflectionType = Type;
 
-  /// Default constructor - initializes with default-constructed value and no comment.
+  /// Default constructor - initializes with default-constructed value and no
+  /// comment.
   Commented() : value_(Type()) {}
 
   /// Constructs from a value without a comment.
@@ -89,7 +91,8 @@ struct Commented {
     requires(std::is_convertible_v<U, Type>)
   Commented(U&& _value) noexcept : value_(std::forward<U>(_value)) {}
 
-  /// Assigns the underlying object to its default value using the Default sentinel.
+  /// Assigns the underlying object to its default value using the Default
+  /// sentinel.
   /// @tparam U The type (must be default constructible)
   /// @param The default sentinel value
   template <class U = Type>
@@ -104,7 +107,8 @@ struct Commented {
   void add_comment(std::string _comment) { comment_ = std::move(_comment); }
 
   /// Returns the comment associated with the field, if any.
-  /// @return An optional containing the comment string, or nullopt if no comment
+  /// @return An optional containing the comment string, or nullopt if no
+  /// comment
   const std::optional<std::string>& comment() const { return comment_; }
 
   /// Returns the underlying value.

include/rfl/comparisons.hpp

@@ -11,6 +11,13 @@ namespace rfl {
 
 template <auto _threshold>
 struct EqualTo {
+  /// @brief Validates that the given value is equal to the threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is exactly equal to the
+  /// compile-time threshold. If not, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -23,6 +30,12 @@ struct EqualTo {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the EqualTo
+  /// constraint.
+  /// @details This function creates a schema object that encodes the equality
+  /// constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;
@@ -36,6 +49,14 @@ struct EqualTo {
 
 template <auto _threshold>
 struct Minimum {
+  /// @brief Validates that the given value is greater than or equal to the
+  /// threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is at least the
+  /// compile-time threshold. If not, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -48,6 +69,12 @@ struct Minimum {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the Minimum
+  /// constraint.
+  /// @details This function creates a schema object that encodes the minimum
+  /// value constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;
@@ -61,6 +88,14 @@ struct Minimum {
 
 template <auto _threshold>
 struct ExclusiveMinimum {
+  /// @brief Validates that the given value is strictly greater than the
+  /// threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is strictly greater than
+  /// the compile-time threshold. If not, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -73,6 +108,12 @@ struct ExclusiveMinimum {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the ExclusiveMinimum
+  /// constraint.
+  /// @details This function creates a schema object that encodes the exclusive
+  /// minimum value constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;
@@ -86,6 +127,14 @@ struct ExclusiveMinimum {
 
 template <auto _threshold>
 struct Maximum {
+  /// @brief Validates that the given value is less than or equal to the
+  /// threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is at most the
+  /// compile-time threshold. If not, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -98,6 +147,12 @@ struct Maximum {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the Maximum
+  /// constraint.
+  /// @details This function creates a schema object that encodes the maximum
+  /// value constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;
@@ -111,6 +166,13 @@ struct Maximum {
 
 template <auto _threshold>
 struct ExclusiveMaximum {
+  /// @brief Validates that the given value is strictly less than the threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is strictly less than the
+  /// compile-time threshold. If not, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -123,6 +185,12 @@ struct ExclusiveMaximum {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the ExclusiveMaximum
+  /// constraint.
+  /// @details This function creates a schema object that encodes the exclusive
+  /// maximum value constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;
@@ -136,6 +204,13 @@ struct ExclusiveMaximum {
 
 template <auto _threshold>
 struct NotEqualTo {
+  /// @brief Validates that the given value is not equal to the threshold.
+  /// @tparam T The type of the value to validate.
+  /// @param _value The value to validate.
+  /// @return Result<T> containing the value if valid, or an error if not.
+  /// @details This function checks if the input value is not equal to the
+  /// compile-time threshold. If it is, it returns an error with a descriptive
+  /// message.
   template <class T>
   static Result<T> validate(T _value) noexcept {
     constexpr auto threshold = static_cast<T>(_threshold);
@@ -148,6 +223,12 @@ struct NotEqualTo {
     return _value;
   }
 
+  /// @brief Converts the validation rule to a schema representation.
+  /// @tparam T The type for which the schema is generated.
+  /// @return parsing::schema::ValidationType representing the NotEqualTo
+  /// constraint.
+  /// @details This function creates a schema object that encodes the
+  /// not-equal-to constraint for serialization or documentation purposes.
   template <class T>
   static parsing::schema::ValidationType to_schema() {
     using ValidationType = parsing::schema::ValidationType;

include/rfl/define_tagged_union.hpp

@@ -7,6 +7,14 @@
 
 namespace rfl {
 
+/// Defines a tagged union type by combining multiple variant types into a
+/// single std::variant. Each alternative from the provided variant types is
+/// included in the resulting union variant. For example, combining
+/// std::variant<int, double> and std::variant<std::string, bool> produces
+/// std::variant<int, double, std::string, bool>.
+/// @tparam _discriminator A string literal used to distinguish this tagged
+/// union type
+/// @tparam TaggedUnionTypes The variant types to merge into the tagged union
 template <internal::StringLiteral _discriminator, class... TaggedUnionTypes>
 using define_tagged_union_t =
     typename internal::define_tagged_union<_discriminator,

include/rfl/msgpack/Reader.hpp

@@ -22,10 +22,20 @@ struct Reader {
   using InputObjectType = msgpack_object_map;
   using InputVarType = msgpack_object;
 
+  /**
+   * @brief Checks if type T has a custom constructor from a msgpack object.
+   * @tparam T The type to check.
+   */
   template <class T>
   static constexpr bool has_custom_constructor =
       (requires(InputVarType var) { T::from_msgpack_obj(var); });
 
+  /**
+   * @brief Retrieves a field from a msgpack array by index.
+   * @param _idx The index of the field to retrieve.
+   * @param _arr The msgpack array.
+   * @return The field at the given index or an error if out of bounds.
+   */
   rfl::Result<InputVarType> get_field_from_array(
       const size_t _idx, const InputArrayType _arr) const noexcept {
     if (_idx >= _arr.size) {
@@ -34,6 +44,12 @@ struct Reader {
     return _arr.ptr[_idx];
   }
 
+  /**
+   * @brief Retrieves a field from a msgpack object by name.
+   * @param _name The name of the field to retrieve.
+   * @param _obj The msgpack object.
+   * @return The value of the field or an error if not found.
+   */
   rfl::Result<InputVarType> get_field_from_object(
       const std::string& _name, const InputObjectType& _obj) const noexcept {
     for (uint32_t i = 0; i < _obj.size; ++i) {
@@ -51,10 +67,23 @@ struct Reader {
     return error("No field named '" + _name + "' was found.");
   }
 
+  /**
+   * @brief Checks if a msgpack object is empty (nil).
+   * @param _var The msgpack object to check.
+   * @return True if the object is nil, false otherwise.
+   */
   bool is_empty(const InputVarType& _var) const noexcept {
     return _var.type == MSGPACK_OBJECT_NIL;
   }
 
+  /**
+   * @brief Converts a msgpack object to a basic C++ type.
+   * Basic types include strings, byte containers, booleans,
+   * floating-point numbers, integers, and literal types (enums).
+   * @tparam T The target type.
+   * @param _var The msgpack object to convert.
+   * @return The converted value or an error if conversion fails.
+   */
   template <class T>
   rfl::Result<T> to_basic_type(const InputVarType& _var) const noexcept {
     const auto type = _var.type;
@@ -105,6 +134,11 @@ struct Reader {
     }
   }
 
+  /**
+   * @brief Converts a msgpack object to an array type.
+   * @param _var The msgpack object to convert.
+   * @return The array or an error if conversion fails.
+   */
   rfl::Result<InputArrayType> to_array(
       const InputVarType& _var) const noexcept {
     if (_var.type != MSGPACK_OBJECT_ARRAY) {
@@ -113,6 +147,11 @@ struct Reader {
     return _var.via.array;
   }
 
+  /**
+   * @brief Converts a msgpack object to a map/object type.
+   * @param _var The msgpack object to convert.
+   * @return The object or an error if conversion fails.
+   */
   rfl::Result<InputObjectType> to_object(
       const InputVarType& _var) const noexcept {
     if (_var.type != MSGPACK_OBJECT_MAP) {
@@ -121,6 +160,13 @@ struct Reader {
     return _var.via.map;
   }
 
+  /**
+   * @brief Reads all elements of a msgpack array using a provided reader.
+   * @tparam ArrayReader The type of the array reader.
+   * @param _array_reader The reader to use for each element.
+   * @param _arr The msgpack array to read.
+   * @return An optional error if any element fails to be read.
+   */
   template <class ArrayReader>
   std::optional<Error> read_array(const ArrayReader& _array_reader,
                                   const InputArrayType& _arr) const noexcept {
@@ -133,6 +179,13 @@ struct Reader {
     return std::nullopt;
   }
 
+  /**
+   * @brief Reads all fields of a msgpack object using a provided reader.
+   * @tparam ObjectReader The type of the object reader.
+   * @param _object_reader The reader to use for each field.
+   * @param _obj The msgpack object to read.
+   * @return An optional error if any field fails to be read.
+   */
   template <class ObjectReader>
   std::optional<Error> read_object(const ObjectReader& _object_reader,
                                    const InputObjectType& _obj) const noexcept {
@@ -149,6 +202,12 @@ struct Reader {
     return std::nullopt;
   }
 
+  /**
+   * @brief Uses a custom constructor to convert a msgpack object to type T.
+   * @tparam T The target type.
+   * @param _var The msgpack object to convert.
+   * @return The constructed object or an error if construction fails.
+   */
   template <class T>
   rfl::Result<T> use_custom_constructor(
       const InputVarType& _var) const noexcept {

include/rfl/parquet/load.hpp

@@ -7,6 +7,18 @@
 
 namespace rfl::parquet {
 
+/**
+ * @brief Loads an object of type T from a file.
+ *
+ * This function reads the contents of the file specified by _fname,
+ * then attempts to deserialize it into an object of type T using the
+ * read<T, Ps...> function.
+ *
+ * @tparam T The type to load from the file.
+ * @tparam Ps Additional template parameters for the read function.
+ * @param _fname The name of the file to load.
+ * @return Result<T> The result of loading and deserializing the file contents.
+ */
 template <class T, class... Ps>
 Result<T> load(const std::string& _fname) {
   const auto read_bytes = [](const auto& _bytes) {