Add "Anatomy of a Service" documentation (#1782)

* Rust documentation improvements

* Add "Anatomy of a Service" documentation

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

@@ -113,7 +113,7 @@ class ServerServiceGeneratorV2(
                 """
                 /// Sets the [`$structName`](crate::operation_shape::$structName) operation.
                 ///
-                /// This should be a closure satisfying the [`Handler`](#{SmithyHttpServer}::operation::Handler) trait.
+                /// This should be an async function satisfying the [`Handler`](#{SmithyHttpServer}::operation::Handler) trait.
                 /// See the [operation module documentation](#{SmithyHttpServer}::operation) for more information.
                 pub fn $fieldName<H, NewExts>(self, value: H) -> $builderName<#{HandlerSetterGenerics:W}>
                 where
@@ -312,7 +312,7 @@ class ServerServiceGeneratorV2(
                     #{SmithyHttpServer}::routing::IntoMakeService::new(self)
                 }
 
-                /// Applies a layer uniformly to all routes.
+                /// Applies a [`Layer`](#{Tower}::Layer) uniformly to all routes.
                 pub fn layer<L>(self, layer: &L) -> $serviceName<L::Service>
                 where
                     L: #{Tower}::Layer<S>

design/src/SUMMARY.md

@@ -18,6 +18,7 @@
   - [Generating Common Service Code](./server/code_generation.md)
   - [Generating the Pokémon Service](./server/pokemon_service.md)
   - [Instrumentation](./server/instrumentation.md)
+  <!-- - [The Anatomy of a Service](./server/anatomy.md) -->
 
 - [RFCs](./rfcs/overview.md)
   - [RFC-0001: Sharing configuration between multiple clients](./rfcs/rfc0001_shared_config.md)

design/src/server/overview.md

@@ -5,3 +5,4 @@ Smithy Rust provides the ability to generate a server whose operations are provi
 - [Generating Common Service Code](./code_generation.md)
 - [Generating the Pokémon Service](./pokemon_service.md)
 - [Instrumentation](./instrumentation.md)
+<!-- - [The Anatomy of a Service](./anatomy.md) -->

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/plugin.rs

@@ -3,7 +3,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-use aws_smithy_http_server::plugin::Plugin;
+use aws_smithy_http_server::{
+    operation::{Operation, OperationShape},
+    plugin::{Pluggable, Plugin},
+};
+use tower::{layer::util::Stack, Layer, Service};
+
+use std::task::{Context, Poll};
 
 /// A [`Service`](tower::Service) that adds a print log.
 #[derive(Clone, Debug)]
@@ -12,15 +18,15 @@ pub struct PrintService<S> {
     name: &'static str,
 }
 
-impl<R, S> tower::Service<R> for PrintService<S>
+impl<R, S> Service<R> for PrintService<S>
 where
-    S: tower::Service<R>,
+    S: Service<R>,
 {
     type Response = S::Response;
     type Error = S::Error;
     type Future = S::Future;
 
-    fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
+    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
         self.inner.poll_ready(cx)
     }
 
@@ -35,7 +41,7 @@ where
 pub struct PrintLayer {
     name: &'static str,
 }
-impl<S> tower::Layer<S> for PrintLayer {
+impl<S> Layer<S> for PrintLayer {
     type Service = PrintService<S>;
 
     fn layer(&self, service: S) -> Self::Service {
@@ -46,26 +52,24 @@ impl<S> tower::Layer<S> for PrintLayer {
     }
 }
 
-/// A [`Plugin`]() for a service builder to add a [`PrintLayer`] over operations.
+/// A [`Plugin`] for a service builder to add a [`PrintLayer`] over operations.
 #[derive(Debug)]
 pub struct PrintPlugin;
+
 impl<P, Op, S, L> Plugin<P, Op, S, L> for PrintPlugin
 where
-    Op: aws_smithy_http_server::operation::OperationShape,
+    Op: OperationShape,
 {
     type Service = S;
-    type Layer = tower::layer::util::Stack<L, PrintLayer>;
+    type Layer = Stack<L, PrintLayer>;
 
-    fn map(
-        &self,
-        input: aws_smithy_http_server::operation::Operation<S, L>,
-    ) -> aws_smithy_http_server::operation::Operation<Self::Service, Self::Layer> {
+    fn map(&self, input: Operation<S, L>) -> Operation<Self::Service, Self::Layer> {
         input.layer(PrintLayer { name: Op::NAME })
     }
 }
 
 /// An extension to service builders to add the `print()` function.
-pub trait PrintExt: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> {
+pub trait PrintExt: Pluggable<PrintPlugin> {
     /// Causes all operations to print the operation name when called.
     ///
     /// This works by applying the [`PrintPlugin`].
@@ -77,4 +81,4 @@ pub trait PrintExt: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> {
     }
 }
 
-impl<Builder> PrintExt for Builder where Builder: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> {}
+impl<Builder> PrintExt for Builder where Builder: Pluggable<PrintPlugin> {}

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

@@ -49,7 +49,7 @@
 //!
 //! ## [`Handler`]
 //!
-//! The [`Handler`] trait is implemented by all closures which accept [`OperationShape::Input`] as their first
+//! The [`Handler`] trait is implemented by all async functions which accept [`OperationShape::Input`] as their first
 //! argument, the remaining arguments implement [`FromParts`](crate::request::FromParts), and return either
 //! [`OperationShape::Output`] when [`OperationShape::Error`] is [`Infallible`](std::convert::Infallible) or
 //! [`Result`]<[`OperationShape::Output`],[`OperationShape::Error`]>. The following are examples of closures which
@@ -191,7 +191,7 @@ pub use upgrade::*;
 
 /// A Smithy operation, represented by a [`Service`](tower::Service) `S` and a [`Layer`](tower::Layer) `L`.
 ///
-/// The `L` is held and applied lazily during [`Operation::upgrade`].
+/// The `L` is held and applied lazily during [`Upgradable::upgrade`].
 pub struct Operation<S, L = Identity> {
     inner: S,
     layer: L,

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

@@ -5,9 +5,11 @@
 
 use crate::operation::Operation;
 
-/// Provides a standard interface for applying [`Plugin`]s to a service builder. This is implemented automatically for all builders.
-/// As [`Plugin`]s modify the way in which [`Operation`]s are [`upgraded`](crate::operation::Upgradable) we can use [`Pluggable`] as a foundation
-/// to write extension traits for all builders.
+/// Provides a standard interface for applying [`Plugin`]s to a service builder. This is implemented automatically for
+/// all builders.
+///
+/// As [`Plugin`]s modify the way in which [`Operation`]s are [`upgraded`](crate::operation::Upgradable) we can use
+/// [`Pluggable`] as a foundation to write extension traits which are implemented for all service builders.
 ///
 /// # Example
 ///
@@ -19,29 +21,34 @@ use crate::operation::Operation;
 ///         self.apply(PrintPlugin)
 ///     }
 /// }
+///
 /// impl<Builder> PrintExt for Builder where Builder: Pluggable<PrintPlugin> {}
 /// ```
 pub trait Pluggable<NewPlugin> {
     type Output;
 
-    /// A service builder applies this `plugin`.
+    /// Applies a [`Plugin`] to the service builder.
     fn apply(self, plugin: NewPlugin) -> Self::Output;
 }
 
-/// Maps one [`Operation`] to another,
-/// parameterised by the protocol `P` and operation shape `Op` to allow for plugin behaviour to be specialised accordingly.
+/// A mapping from one [`Operation`] to another. Used to modify the behavior of
+/// [`Upgradable`](crate::operation::Upgradable) and therefore the resulting service builder,
 ///
-/// This is passed to [`Pluggable::apply`] to modify the behaviour of the builder.
-pub trait Plugin<P, Op, S, L> {
+/// The generics `Protocol` and `Op` allow the behavior to be parameterized.
+///
+/// Every service builder enjoys [`Pluggable`] and therefore can be provided with a [`Plugin`] using
+/// [`Pluggable::apply`].
+pub trait Plugin<Protocol, Op, S, L> {
     type Service;
     type Layer;
 
-    /// Map an [`Operation`] to another.
+    /// Maps an [`Operation`] to another.
     fn map(&self, input: Operation<S, L>) -> Operation<Self::Service, Self::Layer>;
 }
 
 /// An [`Plugin`] that maps an `input` [`Operation`] to itself.
 pub struct IdentityPlugin;
+
 impl<P, Op, S, L> Plugin<P, Op, S, L> for IdentityPlugin {
     type Service = S;
     type Layer = L;

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

@@ -46,9 +46,9 @@ pub trait Router<B> {
     fn match_route(&self, request: &http::Request<B>) -> Result<Self::Service, Self::Error>;
 }
 
-/// A [`Service`] using the a [`Router`] `R` to redirect messages to specific routes.
+/// A [`Service`] using the [`Router`] `R` to redirect messages to specific routes.
 ///
-/// The `Protocol` parameter is used to determine
+/// The `Protocol` parameter is used to determine the serialization of errors.
 pub struct RoutingService<R, Protocol> {
     router: R,
     _protocol: PhantomData<Protocol>,