Add documentation for rfl::AddNamespacedTagsToVariants

Author: bryceschober

docs/concepts/processors.md

@@ -35,6 +35,7 @@ reflect-cpp currently supports the following processors:
 
 - `rfl::AddStructName` 
 - `rfl::AddTagsToVariants` 
+- `rfl::AddNamespacedTagsToVariants` 
 - `rfl::AllowRawPtrs` 
 - `rfl::DefaultIfMissing` 
 - `rfl::NoExtraFields` 
@@ -117,6 +118,89 @@ struct key_pressed_t {
 Note that there are other ways to address problems like this, for instance `rfl::TaggedUnion`.
 Please refer to the relevant sections of the documentation.
 
+### `rfl::AddNamespacedTagsToVariants`
+
+This processor is similar to `rfl::AddTagsToVariants`, but instead of using just the struct name as the tag, it uses the full namespaced type name. This is particularly useful when you have:
+
+1. Structs with the same name in different namespaces
+2. Structs with `rfl::Generic` fields that would otherwise create naming conflicts
+
+#### Use-case: Structs with the same name in different namespaces
+
+Consider this example where `rfl::AddTagsToVariants` would fail:
+
+```cpp
+namespace Result {
+  struct Message {
+    std::string result;
+  };
+}
+
+namespace Error {
+  struct Message {
+    std::string error;
+    int error_id;
+  };
+}
+
+using Messages = std::variant<Result::Message, Error::Message>;
+
+const auto msgs = std::vector<Messages>{
+  Result::Message{.result = "success"},
+  Error::Message{.error = "failure", .error_id = 404}
+};
+
+// This would cause problems with rfl::AddTagsToVariants because both 
+// structs have the same name "Message"
+
+// But this works perfectly:
+const auto json_string = rfl::json::write<rfl::AddNamespacedTagsToVariants>(msgs);
+const auto msgs2 = rfl::json::read<std::vector<Messages>, rfl::AddNamespacedTagsToVariants>(json_string);
+```
+
+The resulting JSON includes the full namespace path:
+
+```json
+[
+  {"Result::Message": {"result": "success"}},
+  {"Error::Message": {"error": "failure", "error_id": 404}}
+]
+```
+
+#### Use-case: Structs with `rfl::Generic` fields that would otherwise create naming conflicts
+
+Another use case is with `rfl::Generic` fields, where multiple structs contain generic fields that would otherwise create naming conflicts:
+
+```cpp
+struct APIResult {
+  rfl::Generic result;  // Could be string, number, object, etc.
+};
+
+struct APIError {
+  rfl::Generic error;   // Could be string, number, object, etc.
+};
+
+using APIResponse = std::variant<APIResult, APIError>;
+
+const auto response = APIResult{.result = std::string("200")};
+
+// Without namespaces, both Generic fields would have the same tag name.
+// With namespaces, they get unique identifiers:
+const auto json_string = rfl::json::write<rfl::AddNamespacedTagsToVariants>(response);
+```
+
+This generates:
+
+```json
+{"APIResult": {"result": {"std::string": "200"}}}
+```
+
+#### When to use `rfl::AddNamespacedTagsToVariants` vs `rfl::AddTagsToVariants`
+
+- Use `rfl::AddTagsToVariants` when struct names are unique and you want shorter, cleaner tags
+- Use `rfl::AddNamespacedTagsToVariants` when you have naming conflicts or need to distinguish between types in different namespaces
+- Custom tags (using `Tag = rfl::Literal<"custom_name">`) work with both processors and are not affected by the namespace handling
+
 ### `rfl::AllowRawPtrs`
 
 By default, reflect-cpp does not allow *reading into* raw pointers, `std::string_view` or `std::span`. 

docs/variants_and_tagged_unions.md

@@ -57,6 +57,44 @@ const auto r2 = rfl::json::read<Shapes, rfl::AddTagsToVariants>(json_string);
 
 Please refer to the section on processors in this documentation for more information.
 
+## Automatic tags with full namespaces
+
+In some cases, you might have struct name conflicts between different namespaces, or types that would generate identical tags when namespaces are removed. For these situations, you can use `rfl::AddNamespacedTagsToVariants` instead:
+
+```cpp
+namespace Result {
+  struct Message {
+    std::string result;
+  };
+}
+
+namespace Error {
+  struct Message {
+    std::string error;
+    int error_id;
+  };
+}
+
+using Messages = std::variant<Result::Message, Error::Message>;
+
+const Messages msg = Error::Message{.error = "Something went wrong", .error_id = 404};
+
+const auto json_string = rfl::json::write<rfl::AddNamespacedTagsToVariants>(msg);
+```
+
+This generates JSON with fully qualified type names:
+
+```json
+{"Error::Message":{"error":"Something went wrong","error_id":404}}
+```
+
+The key differences between `rfl::AddTagsToVariants` and `rfl::AddNamespacedTagsToVariants`:
+
+- `rfl::AddTagsToVariants` uses just the struct name (e.g., `"Message"`)
+- `rfl::AddNamespacedTagsToVariants` uses the full namespaced name (e.g., `"Error::Message"`)
+- Both respect custom tags defined with `using Tag = rfl::Literal<"custom_name">`
+- Use the namespaced version when you are using `rfl::Generic` or need to distinguish between types in different namespaces and don't want to manually tag them as above
+
 ## `rfl::TaggedUnion` (internally tagged)
 
 Another way to solve this problem is to add a tag inside the class. That is why we have provided a helper class for these purposes: `rfl::TaggedUnion`.