Added documentation for the new writer

docs/supporting_your_own_format.md

@@ -73,29 +73,82 @@ struct Writer {
     using OutputObjectType = ...;
     using OutputVarType = ...;
 
-    /// Appends `_var` to the end of `_arr`, thus mutating it.
-    void add(const OutputVarType _var, OutputArrayType* _arr) const noexcept {...}
-
-    /// Returns an empty OutputVarType, the NULL type of the format.
-    OutputVarType empty_var() const noexcept {...}
-
-    /// Generates an OutputVarType from a basic type
-    /// (std::string, bool, floating point or integral).
-    template <class T>
-    OutputVarType from_basic_type(const T& _var) const noexcept {...}
-
-    /// Generates a new, empty array.
-    OutputArrayType new_array() const noexcept {...}
-
-    /// Generates a new, empty object.
-    OutputObjectType new_object() const noexcept {...}
-
-    /// Determines whether the var is empty (whether it is the NULL type).
-    bool is_empty(const OutputVarType& _var) const noexcept {...}
-
-    /// Adds a new field to obj, thus mutating it.
-    void set_field(const std::string& _name, const OutputVarType& _var,
-                   OutputObjectType* _obj) const noexcept {...}
+  /// Sets an empty array as the root element of the document.
+  /// Some serialization formats require you to pass the expected size in
+  /// advance. If you are not working with such a format, you can ignore the
+  /// parameter `_size`. Returns the new array for further modification.
+  OutputArrayType array_as_root(const size_t _size) const noexcept;
+
+  /// Sets an empty object as the root element of the document.
+  /// Some serialization formats require you to pass the expected size in
+  /// advance. If you are not working with such a format, you can ignore the
+  /// parameter `_size`.
+  /// Returns the new object for further modification.
+  OutputObjectType object_as_root(const size_t _size) const noexcept;
+
+  /// Sets a null as the root element of the document. Returns OutputVarType
+  /// containing the null value.
+  OutputVarType null_as_root() const noexcept;
+
+  /// Sets a basic value (bool, numeric, string) as the root element of the
+  /// document. Returns an OutputVarType containing the new value.
+  template <class T>
+  OutputVarType value_as_root(const T& _var) const noexcept;
+
+  /// Adds an empty array to an existing array. Returns the new
+  /// array for further modification.
+  OutputArrayType add_array_to_array(const size_t _size,
+                                     OutputArrayType* _parent) const noexcept;
+
+  /// Adds an empty array to an existing object. The key or name of the field is
+  /// signified by `_name`. Returns the new array for further modification.
+  OutputArrayType add_array_to_object(
+      const std::string& _name, const size_t _size,
+      OutputObjectType* _parent) const noexcept;
+
+  /// Adds an empty object to an existing array. Returns the new
+  /// object for further modification.
+  OutputObjectType add_object_to_array(
+      const size_t _size, OutputArrayType* _parent) const noexcept;
+
+  /// Adds an empty object to an existing object. The key or name of the field
+  /// is signified by `_name`. Returns the new object for further modification.
+  OutputObjectType add_object_to_object(
+      const std::string& _name, const size_t _size,
+      OutputObjectType* _parent) const noexcept;
+
+  /// Adds a basic value (bool, numeric, string) to an array. Returns an
+  /// OutputVarType containing the new value.
+  template <class T>
+  OutputVarType add_value_to_array(const T& _var,
+                                   OutputArrayType* _parent) const noexcept;
+
+  /// Adds a basic value (bool, numeric, string) to an existing object. The key
+  /// or name of the field is signified by `name`. Returns an
+  /// OutputVarType containing the new value.
+  template <class T>
+  OutputVarType add_value_to_object(const std::string& _name, const T& _var,
+                                    OutputObjectType* _parent) const noexcept;
+
+  /// Adds a null value to an array. Returns an
+  /// OutputVarType containing the null value.
+  OutputVarType add_null_to_array(OutputArrayType* _parent) const noexcept;
+
+  /// Adds a null value to an existing object. The key
+  /// or name of the field is signified by `name`. Returns an
+  /// OutputVarType containing the null value.
+  OutputVarType add_null_to_object(const std::string& _name,
+                                   OutputObjectType* _parent) const noexcept;
+
+  /// Signifies to the writer that we do not want to add any further elements to
+  /// this array. Some serialization formats require this. If you are working
+  /// with a serialization format that doesn't, just leave the function empty.
+  void end_array(OutputArrayType* _arr) const noexcept;
+
+  /// Signifies to the writer that we do not want to add any further elements to
+  /// this object. Some serialization formats require this. If you are working
+  /// with a serialization format that doesn't, just leave the function empty.
+  void end_object(OutputObjectType* _obj) const noexcept;
 };
 ```
 
@@ -214,4 +267,4 @@ Your job is to implement the following:
 1. Iterate through `_obj`.
 2. Identify the required index of the field name using `_fct`.
 3. Set the corresponding field in `std::array` to the field value associated with the field name.
-4. Any field that could not be set in steps 1-3 must be set to `std::nullopt`.
+4. Any field that could not be set in steps 1-3 must be set to `std::nullopt`.

include/rfl/parsing/IsReader.hpp

@@ -43,7 +43,7 @@ concept IsReader = requires(R r, std::string name,
   /// floating point, std::string)
   { r.template to_basic_type<T>(var) } -> std::same_as<rfl::Result<T>>;
 
-  /// fct is a function that turns the field name into the field index of the
+  /// _fct is a function that turns the field name into the field index of the
   /// struct. It returns -1, if the fields does not exist on the struct. This
   /// returns an std::array that can be used to build up the struct.
   {

include/rfl/parsing/IsWriter.hpp

@@ -9,50 +9,87 @@ namespace rfl {
 namespace parsing {
 
 template <class W, class T>
-concept IsWriter = requires(W w, T t, std::string name,
+concept IsWriter = requires(W w, T t, std::string name, std::string basic_value,
                             typename W::OutputArrayType arr,
                             typename W::OutputObjectType obj,
                             typename W::OutputVarType var, size_t size) {
+  /// Sets an empty array as the root element of the document.
+  /// Some serialization formats require you to pass the expected size in
+  /// advance. If you are not working with such a format, you can ignore the
+  /// parameter `size`. Returns the new array for further modification.
   { w.array_as_root(size) } -> std::same_as<typename W::OutputArrayType>;
 
+  /// Sets an empty object as the root element of the document.
+  /// Some serialization formats require you to pass the expected size in
+  /// advance. If you are not working with such a format, you can ignore the
+  /// parameter `size`.
+  /// Returns the new object for further modification.
   { w.object_as_root(size) } -> std::same_as<typename W::OutputObjectType>;
 
+  /// Sets a null as the root element of the document. Returns OutputVarType
+  /// containing the null value.
   { w.null_as_root() } -> std::same_as<typename W::OutputVarType>;
 
-  { w.value_as_root(name) } -> std::same_as<typename W::OutputVarType>;
+  /// Sets a basic value (bool, numeric, string) as the root element of the
+  /// document. Returns an OutputVarType containing the new value.
+  { w.value_as_root(basic_value) } -> std::same_as<typename W::OutputVarType>;
 
+  /// Adds an empty array to an existing array. Returns the new
+  /// array for further modification.
   {
     w.add_array_to_array(size, &arr)
     } -> std::same_as<typename W::OutputArrayType>;
 
+  /// Adds an empty object to an existing array. Returns the new
+  /// object for further modification.
   {
     w.add_object_to_array(size, &arr)
     } -> std::same_as<typename W::OutputObjectType>;
 
+  /// Adds an empty array to an existing object. The key or name of the field is
+  /// signified by `name`. Returns the new array for further modification.
   {
     w.add_array_to_object(name, size, &obj)
     } -> std::same_as<typename W::OutputArrayType>;
 
+  /// Adds an empty object to an existing object. The key or name of the field
+  /// is signified by `name`. Returns the new object for further modification.
   {
     w.add_object_to_object(name, size, &obj)
     } -> std::same_as<typename W::OutputObjectType>;
 
+  /// Adds a basic value (bool, numeric, string) to an array. Returns an
+  /// OutputVarType containing the new value.
   {
-    w.add_value_to_array(name, &arr)
+    w.add_value_to_array(basic_value, &arr)
     } -> std::same_as<typename W::OutputVarType>;
 
+  /// Adds a basic value (bool, numeric, string) to an existing object. The key
+  /// or name of the field is signified by `name`. Returns an
+  /// OutputVarType containing the new value.
   {
-    w.add_value_to_object(name, name, &obj)
+    w.add_value_to_object(name, basic_value, &obj)
     } -> std::same_as<typename W::OutputVarType>;
 
+  /// Adds a null value to an array. Returns an
+  /// OutputVarType containing the null value.
   { w.add_null_to_array(&arr) } -> std::same_as<typename W::OutputVarType>;
 
+  /// Adds a null value to an existing object. The key
+  /// or name of the field is signified by `name`. Returns an
+  /// OutputVarType containing the null value.
   {
     w.add_null_to_object(name, &obj)
     } -> std::same_as<typename W::OutputVarType>;
 
+  /// Signifies to the writer that we do not want to add any further elements to
+  /// this array. Some serialization formats require this. If you are working
+  /// with a serialization format that doesn't, just leave the function empty.
   { w.end_array(&arr) } -> std::same_as<void>;
 
+  /// Signifies to the writer that we do not want to add any further elements to
+  /// this object. Some serialization formats require this. If you are working
+  /// with a serialization format that doesn't, just leave the function empty.
   { w.end_object(&obj) } -> std::same_as<void>;
 };