[docs] update extractor docs: fix a typo, increase verbosity

dropshot/src/extractor/body.rs

@@ -30,9 +30,11 @@ use std::fmt::Debug;
 // 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], 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.
 #[derive(Debug)]
 pub struct TypedBody<BodyType: JsonSchema + DeserializeOwned + Send + Sync> {
     inner: BodyType,

dropshot/src/extractor/header.rs

@@ -17,11 +17,14 @@ use crate::{
 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. `PathType` 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.
+/// `HeaderType` from an HTTP request's header values. `HeaderType` 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.  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.
 pub struct Header<HeaderType: DeserializeOwned + JsonSchema + Send + Sync> {
     inner: HeaderType,
 }

dropshot/src/extractor/path.rs

@@ -16,10 +16,12 @@ use schemars::JsonSchema;
 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.
+/// `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.
 #[derive(Debug)]
 pub struct Path<PathType: JsonSchema + Send + Sync> {
     inner: PathType,

dropshot/src/extractor/query.rs

@@ -17,9 +17,12 @@ 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], 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.
 #[derive(Debug)]
 pub struct Query<QueryType: DeserializeOwned + JsonSchema + Send + Sync> {
     inner: QueryType,