Add clarity around 'serde' re-exports.

Closes #2038.

core/lib/src/serde/mod.rs

@@ -1,4 +1,37 @@
-//! Automatic serialization and deserialization support.
+//! Serialization and deserialization support.
+//!
+//! * JSON support is provided by the [`Json`](json::Json) type.
+//! * MessagePack support is provided by the [`MsgPack`](msgpack::MsgPack) type.
+//! * UUID support is provided by the [`UUID`](uuid) type.
+//!
+//! Types implement one or all of [`FromParam`](crate::request::FromParam),
+//! [`FromForm`](crate::form::FromForm), [`FromData`](crate::data::FromData),
+//! and [`Responder`](crate::response::Responder).
+//!
+//! ## Deriving `Serialize`, `Deserialize`
+//!
+//! For convenience, Rocket re-exports `serde`'s `Serialize` and `Deserialize`
+//! traits and derive macros from this module. However, due to Rust's limited
+//! support for derive macro re-exports, using the re-exported derive macros
+//! requires annotating structures with `#[serde(crate = "rocket::serde")]`:
+//!
+//! ```rust
+//! use rocket::serde::{Serialize, Deserialize};
+//!
+//! #[derive(Serialize, Deserialize)]
+//! #[serde(crate = "rocket::serde")]
+//! struct MyStruct {
+//!     foo: String,
+//! }
+//! ```
+//!
+//! If you'd like to avoid this extra annotation, you must depend on `serde`
+//! directly via your crate's `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! serde = { version = "1.0", features = ["derive"] }
+//! ```
 
 #[doc(inline)]
 pub use serde::ser::{Serialize, Serializer};

site/guide/4-requests.md

@@ -668,6 +668,7 @@ data as JSON. The only condition is that the generic type `T` implements the
 use rocket::serde::{Deserialize, json::Json};
 
 #[derive(Deserialize)]
+#[serde(crate = "rocket::serde")]
 struct Task<'r> {
     description: &'r str,
     complete: bool
@@ -677,6 +678,25 @@ struct Task<'r> {
 fn new(task: Json<Task<'_>>) { /* .. */ }
 ```
 
+! warning: Using Rocket's `serde` derive re-exports requires a bit more effort.
+
+  For convenience, Rocket re-exports `serde`'s `Serialize` and `Deserialize`
+  traits and derive macros from `rocket::serde`. However, due to Rust's limited
+  support for derive macro re-exports, using the re-exported derive macros
+  requires annotating structures with `#[serde(crate = "rocket::serde")]`. If
+  you'd like to avoid this extra annotation, you must depend on `serde` directly
+  via your crate's `Cargo.toml`:
+
+  `
+  serde = { version = "1.0", features = ["derive"] }
+  `
+
+  We always use the extra annotation in the guide, but you may prefer the
+  alternative.
+
+See the [JSON example](@example/serialization/src/json.rs) on GitHub for a
+complete example.
+
 ! note: JSON support requires enabling Rocket's `json` feature flag.
 
   Rocket intentionally places JSON support, as well support for other data
@@ -688,9 +708,6 @@ fn new(task: Json<Task<'_>>) { /* .. */ }
   rocket = { version = "0.5.0-rc.1", features = ["json"] }
   `
 
-  See the [JSON example](@example/serialization/src/json.rs) on GitHub for a
-  complete example.
-
 ### Temporary Files
 
 The [`TempFile`] data guard streams data directly to a temporary file which can

site/guide/5-responses.md

@@ -395,6 +395,7 @@ write:
 use rocket::serde::{Serialize, json::Json};
 
 #[derive(Serialize)]
+#[serde(crate = "rocket::serde")]
 struct Task { /* .. */ }
 
 #[get("/todo")]

site/guide/9-configuration.md

@@ -354,6 +354,7 @@ fn rocket() -> _ {
     let figment = rocket.figment();
 
     #[derive(Deserialize)]
+    #[serde(crate = "rocket::serde")]
     struct Config {
         port: u16,
         custom: Vec<String>,
@@ -382,6 +383,7 @@ Because it is common to store configuration in managed state, Rocket provides an
 # #[macro_use] extern crate rocket;
 # use rocket::serde::Deserialize;
 # #[derive(Deserialize)]
+# #[serde(crate = "rocket::serde")]
 # struct Config {
 #     port: u16,
 #     custom: Vec<String>,
@@ -457,6 +459,7 @@ use rocket::fairing::AdHoc;
 use figment::{Figment, Profile, providers::{Format, Toml, Serialized, Env}};
 
 #[derive(Debug, Deserialize, Serialize)]
+#[serde(crate = "rocket::serde")]
 struct Config {
     app_value: usize,
     /* and so on.. */

site/tests/Cargo.toml

@@ -10,7 +10,6 @@ rocket = { path = "../../core/lib", features = ["secrets"] }
 
 [dev-dependencies]
 rocket = { path = "../../core/lib", features = ["secrets", "json"] }
-serde = { version = "1.0", features = ["derive"] }
 rand = "0.8"
 figment = { version = "0.10", features = ["toml", "env"] }