Add documentation for mapping from XML to Rust used by serde #528

Mingun · 2022-12-21T18:28:14Z

Reincarnation of #369.

This PR adds a table to the documentation of de module, that shows how XML pieces could be represented by Rust types. Not all of described concepts are work yet, in that case they are marked with FIXME marker.

Almost each example is proved by doctest, which should guarantee that they does not break in the future.

I would like to include this in the next release which I plan to make this year.

The best way to review is to generate documentation locally (this is PowerShell command):

$env:RUSTDOCFLAGS="--cfg docs_rs"; cargo +nightly doc --all-features

and go to the documentation of the de module.

src/de/mod.rs

dralley

Free to merge after the requested edits

This documentation is very helpful, thanks for adding it!

Co-authored-by: Daniel Alley <dalley@redhat.com>

As promised in tafia#369 (comment)

Mingun · 2022-12-25T11:55:51Z

Thanks for review! In the final push I've also removed unused links that was remained from previous revisions, and copy-paste a one note about multi-root XMLs.

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [quick-xml](https://github.com/tafia/quick-xml) | dependencies | minor | `0.26.0` -> `0.27.1` | --- ### Release Notes <details> <summary>tafia/quick-xml</summary> ### [`v0.27.1`](https://github.com/tafia/quick-xml/blob/HEAD/Changelog.md#0271----2022-12-28) [Compare Source](tafia/quick-xml@v0.27.0...v0.27.1) ##### Bug Fixes - [#530]: Fix an infinite loop leading to unbounded memory consumption that occurs when skipping events on malformed XML with the `overlapped-lists` feature active. - [#530]: Fix an error in the `Deserializer::read_to_end` when `overlapped-lists` feature is active and malformed XML is parsed [#530]: tafia/quick-xml#530 ### [`v0.27.0`](https://github.com/tafia/quick-xml/blob/HEAD/Changelog.md#0270----2022-12-25) [Compare Source](tafia/quick-xml@v0.26.0...v0.27.0) ##### New Features - [#521]: Implement `Clone` for all error types. This required changing `Error::Io` to contain `Arc<std::io::Error>` instead of `std::io::Error` since `std::io::Error` does not implement `Clone`. ##### Bug Fixes - [#490]: Ensure that serialization of map keys always produces valid XML names. In particular, that means that maps with numeric and numeric-like keys (for example, `"42"`) no longer can be serialized because [XML name] cannot start from a digit - [#500]: Fix deserialization of top-level sequences of enums, like ```xml <?xml version="1.0" encoding="UTF-8"?>  <A/> <B/> <C/> ``` - [#514]: Fix wrong reporting `Error::EndEventMismatch` after disabling and enabling `.check_end_names` - [#517]: Fix swapped codes for `\r` and `\n` characters when escaping them - [#523]: Fix incorrect skipping text and CDATA content before any map-like structures in serde deserializer, like ```xml unwanted text<struct>...</struct> ``` - [#523]: Fix incorrect handling of `xs:list`s with encoded spaces: they still act as delimiters, which is confirmed also by mature XmlBeans Java library - [#473]: Fix a hidden requirement to enable serde's `derive` feature to get quick-xml's `serialize` feature for `edition = 2021` or `resolver = 2` crates ##### Misc Changes - [#490]: Removed `$unflatten=` special prefix for fields for serde (de)serializer, because: - it is useless for deserializer - serializer was rewritten and does not require it anymore This prefix allowed you to serialize struct field as an XML element and now replaced by a more thoughtful system explicitly indicating that a field should be serialized as an attribute by prepending `@` character to its name - [#490]: Removed `$primitive=` prefix. That prefix allowed you to serialize struct field as an attribute instead of an element and now replaced by a more thoughtful system explicitly indicating that a field should be serialized as an attribute by prepending `@` character to its name - [#490]: In addition to the `$value` special name for a field a new `$text` special name was added: - `$text` is used if you want to map field to text content only. No markup is expected (but text can represent a list as defined by `xs:list` type) - `$value` is used if you want to map elements with different names to one field, that should be represented either by an `enum`, or by sequence of `enum`s (`Vec`, tuple, etc.), or by string. Use it when you want to map field to any content of the field, text or markup Refer to [documentation] for details. - [#521]: MSRV bumped to 1.52. - [#473]: `serde` feature that used to make some types serializable, renamed to `serde-types` - [#528]: Added documentation for XML to `serde` mapping [#473]: tafia/quick-xml#473 [#490]: tafia/quick-xml#490 [#500]: tafia/quick-xml#500 [#514]: tafia/quick-xml#514 [#517]: tafia/quick-xml#517 [#521]: tafia/quick-xml#521 [#523]: tafia/quick-xml#523 [#528]: tafia/quick-xml#528 [XML name]: https://www.w3.org/TR/xml11/#NT-Name [documentation]: https://docs.rs/quick-xml/0.27.0/quick_xml/de/index.html#difference-between-text-and-value-special-names </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: cabr2-bot <cabr2.help@gmail.com> Co-authored-by: crapStone <crapstone01@gmail.com> Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1692 Reviewed-by: crapStone <crapstone@noreply.codeberg.org> Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org> Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>

Mingun added serde Issues related to mapping from Rust types to XML documentation Issues about improvements or bugs in documentation labels Dec 21, 2022

Mingun requested a review from dralley December 21, 2022 18:28

dralley reviewed Dec 22, 2022

View reviewed changes