Improve service documentation (#2020)

Co-authored-by: Luca Palmieri <[email protected]>

* Add module documentation to `plugin.rs`.

* Remove reference to `FromRequest` in `FromParts`.

* Improve `Route` documentation.

rust-runtime/aws-smithy-http-server/src/plugin/mod.rs

@@ -3,6 +3,53 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+//! The plugin system allows you to build middleware with an awareness of the operation it is applied to.
+//!
+//! The system centers around the [`Plugin`] trait. In addition, this module provides helpers for composing and
+//! combining [`Plugin`]s.
+//!
+//! # Filtered application of a HTTP [`Layer`](tower::Layer)
+//!
+//! ```
+//! # use aws_smithy_http_server::plugin::*;
+//! # let layer = ();
+//! # struct GetPokemonSpecies;
+//! # impl GetPokemonSpecies { const NAME: &'static str = ""; };
+//! // Create a `Plugin` from a HTTP `Layer`
+//! let plugin = HttpLayer(layer);
+//!
+//! // Only apply the layer to operations with name "GetPokemonSpecies"
+//! let plugin = filter_by_operation_name(plugin, |name| name == GetPokemonSpecies::NAME);
+//! ```
+//!
+//! # Construct a [`Plugin`] from a closure that takes as input the operation name
+//!
+//! ```
+//! # use aws_smithy_http_server::plugin::*;
+//! // A `tower::Layer` which requires the operation name
+//! struct PrintLayer {
+//!     name: &'static str
+//! }
+//!
+//! // Create a `Plugin` using `PrintLayer`
+//! let plugin = plugin_from_operation_name_fn(|name| PrintLayer { name });
+//! ```
+//!
+//! # Combine [`Plugin`]s
+//!
+//! ```
+//! # use aws_smithy_http_server::plugin::*;
+//! # let a = (); let b = ();
+//! // Combine `Plugin`s `a` and `b`
+//! let plugin = PluginPipeline::new()
+//!     .push(a)
+//!     .push(b);
+//! ```
+//!
+//! As noted in the [`PluginPipeline`] documentation, the plugins' runtime logic is executed in registration order,
+//! meaning that `a` is run _before_ `b` in the example above.
+//!
+
 mod closure;
 mod filter;
 mod identity;

rust-runtime/aws-smithy-http-server/src/request/mod.rs

@@ -119,8 +119,8 @@ impl<B> RequestParts<B> {
     }
 }
 
-/// Provides a protocol aware extraction from a [`Request`]. This borrows the
-/// [`Parts`], in contrast to [`FromRequest`].
+// NOTE: We cannot reference `FromRequest` here, as a point of contrast, as it's `doc(hidden)`.
+/// Provides a protocol aware extraction from a requests [`Parts`].
 pub trait FromParts<Protocol>: Sized {
     type Rejection: IntoResponse<Protocol>;
 

rust-runtime/aws-smithy-http-server/src/routing/route.rs

@@ -46,12 +46,15 @@ use tower::{
     Service, ServiceExt,
 };
 
-/// How routes are stored inside a [`Router`](super::Router).
+/// A HTTP [`Service`] representing a single route.
+///
+/// The construction of [`Route`] from a named HTTP [`Service`] `S`, erases the type of `S`.
 pub struct Route<B = Body> {
     service: BoxCloneService<Request<B>, Response<BoxBody>, Infallible>,
 }
 
 impl<B> Route<B> {
+    /// Constructs a new [`Route`] from a well-formed HTTP service which is cloneable.
     pub fn new<T>(svc: T) -> Self
     where
         T: Service<Request<B>, Response = Response<BoxBody>, Error = Infallible> + Clone + Send + 'static,