[docs] update extractor docs: fix a typo, increase verbosity (#1388)

Author: joelsa

dropshot/src/extractor/body.rs

@@ -28,11 +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` is any structure of yours
-/// that implements `serde::Deserialize`.  See this module's documentation for
-/// more information.
+/// `BodyType` from an HTTP request body.  `BodyType` may be any struct of yours
+/// 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

@@ -17,9 +17,10 @@ use serde::de::DeserializeOwned;
 use std::fmt::Debug;
 
 /// `Path<PathType>` is an extractor used to deserialize an instance of
-/// `PathType` from an HTTP request's path parameters.  `PathType` is any
-/// structure of yours that implements [serde::Deserialize] and
-/// [schemars::JsonSchema]. See the crate documentation for more information.
+/// `PathType` from an HTTP request's path parameters.  `PathType` may be any
+/// struct of yours that implements [serde::Deserialize] and
+/// [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

@@ -17,9 +17,10 @@ use serde::de::DeserializeOwned;
 use std::fmt::Debug;
 
 /// `Query<QueryType>` is an extractor used to deserialize an instance of
-/// `QueryType` from an HTTP request's query string.  `QueryType` is any
-/// structure of yours that implements [serde::Deserialize] and
-/// [schemars::JsonSchema].  See the crate documentation for more information.
+/// `QueryType` from an HTTP request's query string.  `QueryType` may be any
+/// struct of yours that implements [serde::Deserialize] and
+/// [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 query 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