From 4271dd1caf2363c264d5444c30a4da1fe65f25df Mon Sep 17 00:00:00 2001 From: Loi Nguyen Date: Fri, 31 Jul 2026 22:51:21 +0700 Subject: [PATCH] Document Serde attribute mapping Closes #804 --- Changelog.md | 2 ++ src/events/attributes.rs | 7 +++++++ src/se/mod.rs | 6 +++++- 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/Changelog.md b/Changelog.md index dbc59713..2fa0f6a1 100644 --- a/Changelog.md +++ b/Changelog.md @@ -80,6 +80,7 @@ The MSRV has been raised to 1.86. ### Misc Changes - [#859]: Added an example showing how to pretty-print serialized XML. +- [#804]: Linked the serializer and attribute documentation to the Serde XML mapping guide. - [#983]: Adopted an AI use and contribution policy for new upstream contributions. - [#963]: MSRV bumped to 1.86 (April 2025) - [#963]: Deprecated `Attribute` methods that take a `Decoder` parameter, since @@ -88,6 +89,7 @@ The MSRV has been raised to 1.86. `decode_and_unescape_value_with()`. Use `normalized_value()` and `normalized_value_with()` instead. +[#804]: https://github.com/tafia/quick-xml/issues/804 [#963]: https://github.com/tafia/quick-xml/pull/963 [#977]: https://github.com/tafia/quick-xml/issues/977 [#980]: https://github.com/tafia/quick-xml/issues/980 diff --git a/src/events/attributes.rs b/src/events/attributes.rs index 21e661e7..038224d1 100644 --- a/src/events/attributes.rs +++ b/src/events/attributes.rs @@ -1,6 +1,13 @@ //! Xml Attributes module //! //! Provides an iterator over attributes key/value pairs +//! +//! When using Serde instead of the event API, map a named struct field to an XML +//! attribute with `#[serde(rename = "@name")]`. The same mapping works for both +//! serialization and deserialization; see the [Serde mapping basics] for examples. +//! A flattened map can capture attributes whose names are not known in advance. +//! +//! [Serde mapping basics]: ../../de/index.html#basics use crate::encoding::Decoder; use crate::errors::Result as XmlResult; diff --git a/src/se/mod.rs b/src/se/mod.rs index e76be984..1539d027 100644 --- a/src/se/mod.rs +++ b/src/se/mod.rs @@ -1,4 +1,8 @@ -//! Module to handle custom serde `Serializer` +//! Module to handle custom serde `Serializer`. +//! +//! Serde uses the same XML data-model mapping for serialization and deserialization. +//! See the [mapping basics](../de/index.html#basics) for examples of fields mapped to +//! attributes with `#[serde(rename = "@name")]`, text with `$text`, and elements. /// Implements writing primitives to the underlying writer. /// Implementor must provide `write_str(self, &str) -> Result<(), DeError>` method