Improve service documentation

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

@@ -3,6 +3,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+//! The plugin system allows for parameterized modification of [`Operation`]s during the build procedure.
+//!
+//! The system centers around the [`Plugin`] trait. In addition, this module provides helpers for composing and
+//! combining [`Plugin`]s.
+
 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 any 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,