implement review from @davepacheco

Author: joelsa

dropshot/src/extractor/body.rs

@@ -28,13 +28,10 @@ use std::fmt::Debug;
 
 // TypedBody: body extractor for formats that can be deserialized to a specific
 // type.  Only JSON is currently supported.
-
 /// `TypedBody<BodyType>` is an extractor used to deserialize an instance of
 /// `BodyType` from an HTTP request body.  `BodyType` may be any struct of yours
-/// that implements [serde::Deserialize] and [schemars::JsonSchema], where
-/// primitives and enums have to be wrapped in an outer struct and enums need
-/// to be flattened using the `#[serde(flatten)]` attribute.  See this module's
-/// documentation formore information.
+/// that implements [serde::Deserialize] and [schemars::JsonSchema].
+/// See this module's documentation for more information.
 #[derive(Debug)]
 pub struct TypedBody<BodyType: JsonSchema + DeserializeOwned + Send + Sync> {
     inner: BodyType,

dropshot/src/extractor/header.rs

@@ -19,9 +19,10 @@ use super::{metadata::get_metadata, ExtractorMetadata, SharedExtractor};
 /// `Header<HeaderType>` is an extractor used to deserialize an instance of
 /// `HeaderType` from an HTTP request's header values. `HeaderType` may be any
 /// structure that implements [serde::Deserialize] and [schemars::JsonSchema].
-/// While headers are accessible through [RequestInfo::headers], using this
-/// extractor in an entrypoint causes header inputs to be documented in
-/// OpenAPI output. See the crate documentation for more information.
+/// While headers are always accessible through [RequestInfo::headers] even
+/// without this extractor, using this extractor causes header inputs to be
+/// documented in OpenAPI output.
+/// See the top-level crate documentation for more information.
 ///
 /// Note that (unlike the [`Query`] and [`Path`] extractors) headers are case-
 /// insensitive. You may rename fields with mixed casing (e.g. by using

dropshot/src/extractor/path.rs

@@ -19,9 +19,8 @@ use std::fmt::Debug;
 /// `Path<PathType>` is an extractor used to deserialize an instance of 
 /// `PathType` from an HTTP request's path parameters.  `PathType` may be any 
 /// struct of yours that implements [serde::Deserialize] and 
-/// [schemars::JsonSchema], where primitives and enums have to be wrapped in an
-/// outer struct and enums need to be flattened using the `#[serde(flatten)]` 
-/// attribute.  See this module's documentation formore information.
+/// [schemars::JsonSchema].
+/// See the top-level crate documentation for more information.
 #[derive(Debug)]
 pub struct Path<PathType: JsonSchema + Send + Sync> {
     inner: PathType,

dropshot/src/extractor/query.rs

@@ -19,10 +19,8 @@ use std::fmt::Debug;
 /// `Query<QueryType>` is an extractor used to deserialize an instance of
 /// `QueryType` from an HTTP request's query string.  `QueryType` may be any
 /// struct of yours that implements [serde::Deserialize] and 
-/// [schemars::JsonSchema], where primitives and enums have to be wrapped in
-/// an outer struct and enums need to be flattened using the 
-/// `#[serde(flatten)]` attribute.  See this module's documentation for more
-///  information.
+/// [schemars::JsonSchema].
+/// See the top-level crate documentation for more information.
 #[derive(Debug)]
 pub struct Query<QueryType: DeserializeOwned + JsonSchema + Send + Sync> {
     inner: QueryType,

dropshot/src/lib.rs

@@ -323,13 +323,14 @@
 //!
 //! * [`Query`]`<Q>` extracts parameters from a query string, deserializing them
 //!   into an instance of type `Q`. `Q` must implement `serde::Deserialize` and
-//!   `schemars::JsonSchema`.
+//!   `schemars::JsonSchema`. See below for additional restrictions.
 //! * [`Path`]`<P>` extracts parameters from HTTP path, deserializing them into
 //!   an instance of type `P`. `P` must implement `serde::Deserialize` and
-//!   `schemars::JsonSchema`.
+//!   `schemars::JsonSchema`. See below for additional restrictions.
 //! * [`Header`]`<H>` extracts parameters from HTTP headers, deserializing
 //!   them into an instance of type `H`. `H` must implement
-//!   `serde::Deserialize` and `schemars::JsonSchema`.
+//!   `serde::Deserialize` and `schemars::JsonSchema`. See below for additional
+//!   restrictions.
 //! * [`TypedBody`]`<J>` extracts content from the request body by parsing the
 //!   body as JSON (or form/url-encoded) and deserializing it into an instance
 //!   of type `J`. `J` must implement `serde::Deserialize` and `schemars::JsonSchema`.
@@ -340,6 +341,15 @@
 //!   hope is that this would generally not be needed.  It can be useful to
 //!   implement functionality not provided by Dropshot.
 //!
+//! Generally, the type parameter for the `Query`, `Header`, and `Path` extractors
+//! should be Rust structs. The struct's field _names_ correspond to the keys in
+//! the thing being extracted (i.e., they correspond to qquery parameter names
+//! for `Query`, header names for `Header`, and path component names for `Path`).
+//! The struct's field _values_ should generally be Rust primitives, strings,
+//! or enums containing no data.
+//! There is no facility for automatically parsing the values _again_ (e.g.,
+//! as JSON), which means nested values or enums with data cannot be supported.
+//!
 //! `Query` and `Path` impl `SharedExtractor`.  `TypedBody`, `UntypedBody`,
 //! `StreamingBody`, and `RawRequest` impl `ExclusiveExtractor`.  Your function
 //! may accept 0-5 extractors, but only one can be `ExclusiveExtractor`, and it