From b69c42eb9b9f055e74353c9c149074616eff181f Mon Sep 17 00:00:00 2001
From: Sam Scott <sam.scott89@gmail.com>
Date: Wed, 23 Jan 2019 11:13:18 -0500
Subject: Add documentation and workaroud for `#[serde(flatten)]` usage.

---
 src/lib.rs | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

(limited to 'src/lib.rs')

diff --git a/src/lib.rs b/src/lib.rs
index 15e4036..1c3d33e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -97,7 +97,55 @@
 //! using keys with square brackets in them, or unexpected things can
 //! happen.
 //!
+//! ## Flatten workaround
+//!
+//! A current [known limitation](https://github.com/serde-rs/serde/issues/1183)
+//! in `serde` is deserializing `#[serde(flatten)]` structs for formats which
+//! are not self-describing. This includes query strings: `12` can be an integer
+//! or a string, for example.
+//!
+//! We suggest the following workaround:
+//!
+//! ```
+//! extern crate serde;
+//! #[macro_use]
+//! extern crate serde_derive;
+//! extern crate serde_qs as qs;
+//!
+//! use serde::de::Error;
 //! 
+//! fn from_str<'de, D, S>(deserializer: D) -> Result<S, D::Error>
+//!     where D: serde::Deserializer<'de>,
+//!           S: std::str::FromStr
+//! {
+//!     let s = <&str as serde::Deserialize>::deserialize(deserializer)?;
+//!     S::from_str(&s).map_err(|_| D::Error::custom("could not parse string"))
+//! }
+//!
+//! #[derive(Deserialize, Serialize, Debug, PartialEq)]
+//! struct Query {
+//!     a: u8,
+//!     #[serde(flatten)]
+//!     common: CommonParams,
+//! }
+//!
+//! #[derive(Deserialize, Serialize, Debug, PartialEq)]
+//! struct CommonParams {
+//!     #[serde(deserialize_with="from_str")]
+//!     limit: u64,
+//!     #[serde(deserialize_with="from_str")]
+//!     offset: u64,
+//!     #[serde(deserialize_with="from_str")]
+//!     remaining: bool,
+//! }
+//!
+//! fn main() {
+//!     let params = "a=1&limit=100&offset=50&remaining=true";
+//!     let query = Query { a: 1, common: CommonParams { limit: 100, offset: 50, remaining: true } };
+//!     let rec_query: Result<Query, _> = qs::from_str(params);
+//!     assert_eq!(rec_query.unwrap(), query);
+//! }
+//! ```
 
 #![allow(
 )]
-- 
cgit v1.2.3