From fe9fd9a81b04a96844b95bdf76c2da4b26aad82c Mon Sep 17 00:00:00 2001 From: phil Date: Tue, 1 Apr 2025 16:27:03 -0400 Subject: [PATCH 1/2] Compat note for RawValue/flattening & tagged enum It's not obvious that RawValue can't be used with serveral serde features, and the runtime errors are quite opaque. From the number of issues on github and annecdotally, people get bit by this fairly often. This change simply adds a note to RawValue's doc comments about two such scenarios that it won't work with. The phrasing could probably be improved/tightned up and maybe links could be added to explain why? My brain is just fried from running into both cases today and not getting anything done as a result. Alternately ----------- - It seems like these cases might be resolveable by https://github.com/serde-rs/serde/issues/1183 . Maybe this doc comment could reference that issue directly, instead. - Maybe the error messages could somehow be improved? --- src/raw.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/raw.rs b/src/raw.rs index be4dad44d..0aa6df621 100644 --- a/src/raw.rs +++ b/src/raw.rs @@ -111,6 +111,17 @@ use serde::ser::{Serialize, SerializeStruct, Serializer}; /// struct SomeStruct { /// raw_value: Box, /// } +/// +/// # Serde feature compatibility +/// +/// You cannot use `RawValue` on any field of a struct that gets +/// `#[serde(flatten)]`ed into an outer struct. +/// +/// You also cannot use `RawValue` in any variant of an internally-tagged enum. +/// +/// Flattened structs and internally tagged enums use intermediate data +/// structures during deserialization which lose the magic token required for +/// `RawValue` to work. /// ``` #[cfg_attr(docsrs, doc(cfg(feature = "raw_value")))] #[repr(transparent)] From b2b1de1856ea391ffdb477d02ff00f81bc56f1f8 Mon Sep 17 00:00:00 2001 From: phil Date: Tue, 1 Apr 2025 17:02:45 -0400 Subject: [PATCH 2/2] fix doc comment syntax --- src/raw.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/raw.rs b/src/raw.rs index 0aa6df621..143b22212 100644 --- a/src/raw.rs +++ b/src/raw.rs @@ -111,6 +111,7 @@ use serde::ser::{Serialize, SerializeStruct, Serializer}; /// struct SomeStruct { /// raw_value: Box, /// } +/// ``` /// /// # Serde feature compatibility /// @@ -122,7 +123,6 @@ use serde::ser::{Serialize, SerializeStruct, Serializer}; /// Flattened structs and internally tagged enums use intermediate data /// structures during deserialization which lose the magic token required for /// `RawValue` to work. -/// ``` #[cfg_attr(docsrs, doc(cfg(feature = "raw_value")))] #[repr(transparent)] pub struct RawValue {