From 05c0b40cabc73ba0902feaaa23b04793f3844def Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 7 Feb 2026 22:45:39 +0000 Subject: [PATCH 1/2] docs: add documentation for rfl::Commented feature - Created docs/commented.md with examples for YAML and XML. - Updated mkdocs.yaml to include rfl::Commented in the navigation. - Added rfl::Commented to the feature overview in README.md. Co-authored-by: liuzicheng1987 <19538706+liuzicheng1987@users.noreply.github.com> --- README.md | 1 + docs/commented.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yaml | 1 + 3 files changed, 83 insertions(+) create mode 100644 docs/commented.md diff --git a/README.md b/README.md index f82b555b..e044bd53 100644 --- a/README.md +++ b/README.md @@ -571,6 +571,7 @@ In addition, it supports the following custom containers: - `rfl::Binary`: Used to express numbers in binary format. - `rfl::Box`: Similar to `std::unique_ptr`, but (almost) guaranteed to never be null. - `rfl::Bytestring`: An alias for `std::vector`. Supported by Avro, BSON, Cap'n Proto, CBOR, flexbuffers, msgpack and UBJSON. +- `rfl::Commented`: Allows you to add comments to fields (supported by YAML and XML). - `rfl::Generic`: A catch-all type that can represent (almost) anything. - `rfl::Hex`: Used to express numbers in hex format. - `rfl::Literal`: An explicitly enumerated string. diff --git a/docs/commented.md b/docs/commented.md new file mode 100644 index 00000000..e04e45b0 --- /dev/null +++ b/docs/commented.md @@ -0,0 +1,81 @@ +# `rfl::Commented` + +The `rfl::Commented` wrapper allows you to add comments to fields in your structs. These comments are then serialized in formats that support them, such as YAML and XML. + +Note that `rfl::Commented` is currently unsupported by formats that do not have a standard way of representing comments, such as JSON. + +## Example (YAML) + +In YAML, the comments are added as line comments (`#`): + +```cpp +struct Person { + std::string first_name; + std::string last_name; + rfl::Commented town; +}; + +const auto homer = Person{.first_name = "Homer", + .last_name = "Simpson", + .town = rfl::Commented( + "Springfield", "The town where Homer lives")}; + +const auto yaml_str = rfl::yaml::write(homer); +``` + +This will result in the following YAML: + +```yaml +first_name: Homer +last_name: Simpson +town: Springfield # The town where Homer lives +``` + +## Example (XML) + +In XML, the comments are added as `` blocks after the field: + +```cpp +struct Person { + std::string first_name; + std::string last_name; + rfl::Commented town; +}; + +const auto homer = Person{.first_name = "Homer", + .last_name = "Simpson", + .town = rfl::Commented( + "Springfield", "The town where Homer lives")}; + +const auto xml_str = rfl::xml::write(homer); +``` + +This will result in the following XML: + +```xml + + + Homer + Simpson + Springfield + + +``` + +## API convenience + +`rfl::Commented` provides several ways to access and modify the underlying value and the comment: + +- `.get()`, `.value()`, `operator()()` — access the underlying value (const and non-const overloads). +- `.comment()` — returns an `std::optional` containing the comment. +- `.add_comment(std::string)` — sets or updates the comment. +- `.set(...)`, `operator=(...)` — assign the underlying value. + +Example: + +```cpp +Person p; +p.town = "Springfield"; +p.town.add_comment("The town where Homer lives"); +std::string s = p.town.value(); +``` diff --git a/mkdocs.yaml b/mkdocs.yaml index 988c1339..24e7e1fd 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -123,6 +123,7 @@ nav: - rfl::Box and rfl::Ref: rfl_ref.md - rfl::Timestamp: timestamps.md - rfl::Skip: rfl_skip.md + - rfl::Commented: commented.md - rfl::Result: result.md - Standard containers: standard_containers.md - C arrays and inheritance: c_arrays_and_inheritance.md From f507dc16828dd3c9f4c028de0e89bbc6be59a84a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 7 Feb 2026 22:48:40 +0000 Subject: [PATCH 2/2] docs: add documentation for rfl::Commented feature - Created docs/commented.md with examples for YAML and XML. - Highlighted that comments are write-only and ignored during deserialization. - Updated mkdocs.yaml to include rfl::Commented in the navigation. - Added rfl::Commented to the feature overview in README.md. Co-authored-by: liuzicheng1987 <19538706+liuzicheng1987@users.noreply.github.com> --- docs/commented.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commented.md b/docs/commented.md index e04e45b0..494bceee 100644 --- a/docs/commented.md +++ b/docs/commented.md @@ -2,7 +2,7 @@ The `rfl::Commented` wrapper allows you to add comments to fields in your structs. These comments are then serialized in formats that support them, such as YAML and XML. -Note that `rfl::Commented` is currently unsupported by formats that do not have a standard way of representing comments, such as JSON. +Note that `rfl::Commented` is currently unsupported by formats that do not have a standard way of representing comments, such as JSON. Also note that comments are **write-only**: they are ignored during deserialization. ## Example (YAML)