Update documentation to clarify strict encoding modes.

4 files changed, 31 insertions, 3 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 8ea1c37..d832662 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,7 +8,7 @@ license = "MIT/Apache-2.0"
 name = "serde_qs"
 repository = "https://github.com/samscott89/serde_qs"
 readme = "README.md"
-version = "0.4.1"
+version = "0.4.2"
 
 [badges]
 
diff --git a/README.md b/README.md
index a2ef973..034e9dd 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ This crate works with Cargo and can be found on
 
 ```toml
 [dependencies]
-serde_qs = "0.4.1"
+serde_qs = "0.4.2"
 ```
 
 [crates.io]: https://crates.io/crates/serde_qs
diff --git a/examples/introduction.rs b/examples/introduction.rs
index 9878968..a1f6fc9 100644
--- a/examples/introduction.rs
+++ b/examples/introduction.rs
@@ -72,7 +72,7 @@ fn main() {
     //
     // (For this round trip to work, it's necessary to parse the query string
     // in non-strict mode, to allow parsing of url_encoded square brackets
-    // in the key).
+    // in the key. See the lib.rs documentation for why).
     let qs_non_strict = Config::new(5, false);
     let params: QueryParams = qs_non_strict.deserialize_str(&encoded).unwrap();
     assert_eq!(params, example_params);
diff --git a/src/lib.rs b/src/lib.rs
index 2da9b2a..b2bd63c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -70,6 +70,34 @@
 //! assert_eq!(rec_params, params);
 //!
 //! # }
+//! ```
+//!
+//! ## Strict vs Non-Strict modes
+//!
+//! `serde_qs` supports two operating modes, which can be specified using
+//! [`Config`](struct.Config.html), and is all about how `serde_qs` handles square brackets.
+//!
+//! Techncially, square brackets should be encoded in URLs as `%5B` and `%5D`.
+//! However, they are often used in their raw format to specify querystrings
+//! such as `a[b]=123`.
+//!
+//! In strict mode, `serde_qs` will only tolerate unencoded square brackets
+//! to denote nested keys. So `a[b]=123` will decode as `{"a": {"b": 123}}`.
+//! This means that encoded square brackets can actually be part of the key.
+//! `a[b%5Bc%5D]=123` becomes `{"a": {"b[c]": 123}}`.
+//!
+//! However, since some implementations will automatically encode everything
+//! in the URL, we also have a non-strict mode. This means that `serde_qs`
+//! will assume that any encoded square brackets in the string were meant to
+//! be taken as nested keys. From the example before, `a[b%5Bc%5D]=123` will 
+//! now become `{"a": {"b": {"c": 123 }}}`.
+//!
+//! Non-strict mode can be useful when, as said before, some middleware
+//! automatically encodes the brackets. But care must be taken to avoid
+//! using keys with square brackets in them, or unexpected things can
+//! happen.
+//!
+//! 
 
 #![allow(
 )]