Skip to content

Document Serde attribute mapping #998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lntutor wants to merge 1 commit into
base: master
Choose a base branch
from
+14 −1
Open

Document Serde attribute mapping #998

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions Changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions src/events/attributes.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

@dralley dralley Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't feel like the appropriate place for this specific documentation. If this isn't already documented in src/de then it might make sense there. I presume it already is given the link.

@dralley dralley Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other words, this ought to be removed.

@dralley dralley Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The discussion on the issue already mentions this, too. If it needs to be more visible, then please suggest somewhere that is more visible - but the core attributes docs isn't appropriate.


use crate::encoding::Decoder;
use crate::errors::Result as XmlResult;
Expand Down
6 changes: 5 additions & 1 deletion src/se/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading