From e6e7a2f7dd45c4ca27171d13ffd1dd3d66352e49 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Tue, 22 Nov 2022 15:36:51 +0100
Subject: [PATCH 01/23] Document the new service builder

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 512ccd6912..f66dc2f153 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -321,6 +321,79 @@ class ServerServiceGeneratorV2(
 
         rustTemplate(
             """
+            /// The [`$serviceName`] is the place where you can register
+            /// your service's operation implementations.
+            ///
+            /// Use [`$builderName`] to construct the
+            /// `$serviceName`. For each of the [operations] modeled in
+            /// your Smithy service, you need to provide an implementation in the
+            /// form of a Rust async function or closure that takes in the
+            /// operation's input as their first parameter, and returns the
+            /// operation's output. If your operation is fallible (i.e. it
+            /// contains the `errors` member in your Smithy model), the function
+            /// implementing the operation has to be fallible (i.e. return a
+            /// [`Result`]). **You must register an implementation for all
+            /// operations with the correct signature**, or your application
+            /// will fail to compile.
+            ///
+            /// [`$serviceName`] implements [`tower::make::MakeService`], a _service
+            /// factory_. You can feed this value to a [Hyper server], and the
+            /// server will instantiate and [`serve`] your service, calling [`$serviceName::into_make_service`].
+            ///
+            /// [`$serviceName::into_make_service_with_connect_info`] converts $serviceName into [`tower::make::MakeService`]
+            /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
+            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server].
+            ///
+            /// Here's a full example to get you started:
+            ///
+            /// ```rust
+            /// use std::net::SocketAddr;
+            /// use pokemon_service_server_sdk::{input, output, error};
+            ///
+            /// ##[tokio::main]
+            /// pub async fn main() {
+            ///    let app = PokemonService::builder_without_plugins()
+            ///        .check_health(check_health)
+            ///        .do_nothing(do_nothing)
+            ///        .get_pokemon_species(get_pokemon_species)
+            ///        .build()
+            ///        .expect("failed to build an instance of PokemonService");
+            ///
+            ///    let bind: SocketAddr = format!("{}:{}", "127.0.0.1", "6969")
+            ///        .parse()
+            ///        .expect("unable to parse the server bind address and port");
+            ///
+            ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
+            ///
+            ///    // Run your service!
+            ///    // if let Err(err) = server.await {
+            ///    //   eprintln!("server error: {}", err);
+            ///    // }
+            /// }
+            ///
+            /// /// Health check operation, to check the service is up
+            /// /// Not (yet) a deep check
+            /// async fn check_health(input: input::CheckHealthInput) -> Result<output::CheckHealthOutput, error::CheckHealthError> {
+            ///     todo!()
+            /// }
+            ///
+            /// /// DoNothing operation, used to stress test the framework.
+            /// async fn do_nothing(input: input::DoNothingInput) -> Result<output::DoNothingOutput, error::DoNothingError> {
+            ///     todo!()
+            /// }
+            ///
+            /// /// Retrieve information about a Pokémon species.
+            /// async fn get_pokemon_species(input: input::GetPokemonSpeciesInput) -> Result<output::GetPokemonSpeciesOutput, error::GetPokemonSpeciesError> {
+            ///     todo!()
+            /// }
+            ///
+            /// ```
+            ///
+            /// [`serve`]: https://docs.rs/hyper/0.14.16/hyper/server/struct.Builder.html##method.serve
+            /// [`tower::make::MakeService`]: https://docs.rs/tower/latest/tower/make/trait.MakeService.html
+            /// [HTTP binding traits]: https://awslabs.github.io/smithy/1.0/spec/core/http-traits.html
+            /// [operations]: https://awslabs.github.io/smithy/1.0/spec/core/model.html##operation
+            /// [Hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
             ##[derive(Clone)]
             pub struct $serviceName<S = #{SmithyHttpServer}::routing::Route> {
                 router: #{SmithyHttpServer}::routers::RoutingService<#{Router}<S>, #{Protocol}>,

From 3dfc04be9b8f6f2aa81015d8cb21708c8fcaefbb Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Tue, 22 Nov 2022 18:04:18 +0100
Subject: [PATCH 02/23] Generate docs for current service

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 31 ++++++-------------
 1 file changed, 9 insertions(+), 22 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index f66dc2f153..1aeb387a6d 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -319,10 +319,13 @@ class ServerServiceGeneratorV2(
     private fun serviceStruct(): Writable = writable {
         documentShape(service, model)
 
+        val functionSignatures =
+            operations.joinToString("\n") { "/// async fn ${builderFieldNames[it]}(input: input::${it.input.get().name}) -> Result<output::${it.output.get().name}, error::${it.id.name}Error> { todo!() }" }
+
         rustTemplate(
             """
-            /// The [`$serviceName`] is the place where you can register
-            /// your service's operation implementations.
+            /// The [`$builderName`] is the place where you can register
+            /// your service $serviceName's operation implementations.
             ///
             /// Use [`$builderName`] to construct the
             /// `$serviceName`. For each of the [operations] modeled in
@@ -352,12 +355,10 @@ class ServerServiceGeneratorV2(
             ///
             /// ##[tokio::main]
             /// pub async fn main() {
-            ///    let app = PokemonService::builder_without_plugins()
-            ///        .check_health(check_health)
-            ///        .do_nothing(do_nothing)
-            ///        .get_pokemon_species(get_pokemon_species)
+            ///    let app = $serviceName::builder_without_plugins()
+            ${builderFieldNames.values.joinToString("\n") { "///        .$it($it)" }}
             ///        .build()
-            ///        .expect("failed to build an instance of PokemonService");
+            ///        .expect("failed to build an instance of $serviceName");
             ///
             ///    let bind: SocketAddr = format!("{}:{}", "127.0.0.1", "6969")
             ///        .parse()
@@ -371,21 +372,7 @@ class ServerServiceGeneratorV2(
             ///    // }
             /// }
             ///
-            /// /// Health check operation, to check the service is up
-            /// /// Not (yet) a deep check
-            /// async fn check_health(input: input::CheckHealthInput) -> Result<output::CheckHealthOutput, error::CheckHealthError> {
-            ///     todo!()
-            /// }
-            ///
-            /// /// DoNothing operation, used to stress test the framework.
-            /// async fn do_nothing(input: input::DoNothingInput) -> Result<output::DoNothingOutput, error::DoNothingError> {
-            ///     todo!()
-            /// }
-            ///
-            /// /// Retrieve information about a Pokémon species.
-            /// async fn get_pokemon_species(input: input::GetPokemonSpeciesInput) -> Result<output::GetPokemonSpeciesOutput, error::GetPokemonSpeciesError> {
-            ///     todo!()
-            /// }
+            $functionSignatures
             ///
             /// ```
             ///

From 79dc931280579db1f4c08ebc439295edd6622bf0 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 23 Nov 2022 11:18:14 +0100
Subject: [PATCH 03/23] Address comments

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 1aeb387a6d..7cd501a63f 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -330,7 +330,7 @@ class ServerServiceGeneratorV2(
             /// Use [`$builderName`] to construct the
             /// `$serviceName`. For each of the [operations] modeled in
             /// your Smithy service, you need to provide an implementation in the
-            /// form of a Rust async function or closure that takes in the
+            /// form of an async function that takes in the
             /// operation's input as their first parameter, and returns the
             /// operation's output. If your operation is fallible (i.e. it
             /// contains the `errors` member in your Smithy model), the function
@@ -339,9 +339,9 @@ class ServerServiceGeneratorV2(
             /// operations with the correct signature**, or your application
             /// will fail to compile.
             ///
-            /// [`$serviceName`] implements [`tower::make::MakeService`], a _service
-            /// factory_. You can feed this value to a [Hyper server], and the
-            /// server will instantiate and [`serve`] your service, calling [`$serviceName::into_make_service`].
+            /// [`$serviceName`] can be converted into a type that implements [`tower::make::MakeService`], a _service
+            /// factory_, calling [`$serviceName::into_make_service`]. You can feed this value to a [Hyper server], and the
+            /// server will instantiate and [`serve`] your service.
             ///
             /// [`$serviceName::into_make_service_with_connect_info`] converts $serviceName into [`tower::make::MakeService`]
             /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).

From ddbedf122073c387d448492e100c1231c9d87dc1 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 23 Nov 2022 11:22:26 +0100
Subject: [PATCH 04/23] Rename variable

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt     | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 7cd501a63f..5c0cad52ac 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -23,7 +23,7 @@ import software.amazon.smithy.rust.codegen.server.smithy.ServerCargoDependency
 import software.amazon.smithy.rust.codegen.server.smithy.generators.protocol.ServerProtocol
 
 class ServerServiceGeneratorV2(
-    codegenContext: CodegenContext,
+    private val codegenContext: CodegenContext,
     private val protocol: ServerProtocol,
 ) {
     private val runtimeConfig = codegenContext.runtimeConfig
@@ -319,15 +319,18 @@ class ServerServiceGeneratorV2(
     private fun serviceStruct(): Writable = writable {
         documentShape(service, model)
 
-        val functionSignatures =
-            operations.joinToString("\n") { "/// async fn ${builderFieldNames[it]}(input: input::${it.input.get().name}) -> Result<output::${it.output.get().name}, error::${it.id.name}Error> { todo!() }" }
+        val functionImpls =
+            operations.joinToString("\n") {
+                "/// async fn ${builderFieldNames[it]}(input: input::${it.input.get().name}) -> " +
+                    "Result<output::${it.output.get().name}, error::${it.id.name}Error> { todo!() }"
+            }
 
         rustTemplate(
             """
             /// The [`$builderName`] is the place where you can register
             /// your service $serviceName's operation implementations.
             ///
-            /// Use [`$builderName`] to construct the
+            /// Use [`$serviceName::builder_without_plugins()`] to construct the $builderName, to build
             /// `$serviceName`. For each of the [operations] modeled in
             /// your Smithy service, you need to provide an implementation in the
             /// form of an async function that takes in the
@@ -351,7 +354,7 @@ class ServerServiceGeneratorV2(
             ///
             /// ```rust
             /// use std::net::SocketAddr;
-            /// use pokemon_service_server_sdk::{input, output, error};
+            /// use ${codegenContext.moduleUseName()}::{input, output, error, $serviceName};
             ///
             /// ##[tokio::main]
             /// pub async fn main() {
@@ -360,8 +363,7 @@ class ServerServiceGeneratorV2(
             ///        .build()
             ///        .expect("failed to build an instance of $serviceName");
             ///
-            ///    let bind: SocketAddr = format!("{}:{}", "127.0.0.1", "6969")
-            ///        .parse()
+            ///    let bind: SocketAddr = "127.0.0.1:6969".parse()
             ///        .expect("unable to parse the server bind address and port");
             ///
             ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
@@ -372,7 +374,7 @@ class ServerServiceGeneratorV2(
             ///    // }
             /// }
             ///
-            $functionSignatures
+            $functionImpls
             ///
             /// ```
             ///

From f7a2393cc12d3141824977c7fdc656d9a689b56d Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 23 Nov 2022 12:53:10 +0100
Subject: [PATCH 05/23] Change handler names

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../codegen/server/smithy/generators/DocHandlerGenerator.kt   | 4 ++--
 .../server/smithy/generators/ServerOperationShapeGenerator.kt | 2 +-
 .../server/smithy/generators/ServerServiceGeneratorV2.kt      | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/DocHandlerGenerator.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/DocHandlerGenerator.kt
index 476f364709..083495970e 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/DocHandlerGenerator.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/DocHandlerGenerator.kt
@@ -22,7 +22,7 @@ import software.amazon.smithy.rust.codegen.core.util.outputShape
 /**
 Generates a stub for use within documentation.
  */
-class DocHandlerGenerator(private val operation: OperationShape, private val commentToken: String = "//", codegenContext: CodegenContext) {
+class DocHandlerGenerator(private val operation: OperationShape, private val commentToken: String = "//", private val handlerName: String, codegenContext: CodegenContext) {
     private val model = codegenContext.model
     private val symbolProvider = codegenContext.symbolProvider
     private val crateName = codegenContext.moduleUseName()
@@ -49,7 +49,7 @@ class DocHandlerGenerator(private val operation: OperationShape, private val com
                 """
                 $commentToken ## use $crateName::${Inputs.namespace}::${inputSymbol.name};
                 $commentToken ## use $crateName::${Outputs.namespace}::${outputSymbol.name};
-                $commentToken async fn handler(input: ${inputSymbol.name}) -> $outputT {
+                $commentToken async fn $handlerName(input: ${inputSymbol.name}) -> $outputT {
                 $commentToken     todo!()
                 $commentToken }
                 """.trimIndent(),
diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt
index 8ae62beca1..4f650f1999 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt
@@ -62,7 +62,7 @@ class ServerOperationShapeGenerator(
             "SmithyHttpServer" to
                 ServerCargoDependency.SmithyHttpServer(codegenContext.runtimeConfig).toType(),
             "Tower" to ServerCargoDependency.Tower.toType(),
-            "Handler" to DocHandlerGenerator(operations[0], "//!", codegenContext)::render,
+            "Handler" to DocHandlerGenerator(operations[0], "//!", "handler", codegenContext)::render,
         )
         for (operation in operations) {
             ServerOperationGenerator(codegenContext, operation).render(writer)
diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 76ef7b40bd..bc9406834c 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -156,7 +156,7 @@ class ServerServiceGeneratorV2(
                 }
                 """,
                 "Protocol" to protocol.markerStruct(),
-                "Handler" to DocHandlerGenerator(operationShape, "///", codegenContext)::render,
+                "Handler" to DocHandlerGenerator(operationShape, "///", "handler", codegenContext)::render,
                 *codegenScope,
             )
 
@@ -343,7 +343,7 @@ class ServerServiceGeneratorV2(
 
         val handlers: Writable = operations
             .map { operation ->
-                DocHandlerGenerator(operation, "///", codegenContext).docSignature()
+                DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature()
             }
             .reduce { acc, wt ->
                 writable {

From 7a13a5f84b2b0ab73a5463ba4378ca2f41437b59 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Thu, 24 Nov 2022 11:55:00 +0100
Subject: [PATCH 06/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 161 ++++++++++--------
 1 file changed, 94 insertions(+), 67 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index bc9406834c..30a492a4a1 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -341,74 +341,8 @@ class ServerServiceGeneratorV2(
     private fun serviceStruct(): Writable = writable {
         documentShape(service, model)
 
-        val handlers: Writable = operations
-            .map { operation ->
-                DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature()
-            }
-            .reduce { acc, wt ->
-                writable {
-                    rustTemplate("#{acc:W} \n#{wt:W}", "acc" to acc, "wt" to wt)
-                }
-            }
-
         rustTemplate(
             """
-            /// The [`$builderName`] is the place where you can register
-            /// your service $serviceName's operation implementations.
-            ///
-            /// Use [`$serviceName::builder_without_plugins()`] to construct the $builderName, to build
-            /// `$serviceName`. For each of the [operations] modeled in
-            /// your Smithy service, you need to provide an implementation in the
-            /// form of an async function that takes in the
-            /// operation's input as their first parameter, and returns the
-            /// operation's output. If your operation is fallible (i.e. it
-            /// contains the `errors` member in your Smithy model), the function
-            /// implementing the operation has to be fallible (i.e. return a
-            /// [`Result`]). **You must register an implementation for all
-            /// operations with the correct signature**, or your service
-            /// will fail to build at runtime and panic.
-            ///
-            /// [`$serviceName`] can be converted into a type that implements [`tower::make::MakeService`], a _service
-            /// factory_, calling [`$serviceName::into_make_service`]. You can feed this value to a [Hyper server], and the
-            /// server will instantiate and [`serve`] your service.
-            ///
-            /// [`$serviceName::into_make_service_with_connect_info`] converts $serviceName into [`tower::make::MakeService`]
-            /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
-            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server].
-            ///
-            /// Here's a full example to get you started:
-            ///
-            /// ```rust
-            /// use std::net::SocketAddr;
-            /// use ${codegenContext.moduleUseName()}::$serviceName;
-            ///
-            /// ##[tokio::main]
-            /// pub async fn main() {
-            ///    let app = $serviceName::builder_without_plugins()
-            ${builderFieldNames.values.joinToString("\n") { "///        .$it($it)" }}
-            ///        .build()
-            ///        .expect("failed to build an instance of $serviceName");
-            ///
-            ///    let bind: SocketAddr = "127.0.0.1:6969".parse()
-            ///        .expect("unable to parse the server bind address and port");
-            ///
-            ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
-            ///
-            ///    // Run your service!
-            ///    // if let Err(err) = server.await {
-            ///    //   eprintln!("server error: {}", err);
-            ///    // }
-            /// }
-            ///
-            #{Handlers:W}
-            ///
-            /// ```
-            ///
-            /// [`serve`]: https://docs.rs/hyper/0.14.16/hyper/server/struct.Builder.html##method.serve
-            /// [`tower::make::MakeService`]: https://docs.rs/tower/latest/tower/make/trait.MakeService.html
-            /// [HTTP binding traits]: https://awslabs.github.io/smithy/1.0/spec/core/http-traits.html
-            /// [operations]: https://awslabs.github.io/smithy/1.0/spec/core/model.html##operation
-            /// [Hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
             ##[derive(Clone)]
             pub struct $serviceName<S = #{SmithyHttpServer}::routing::Route> {
                 router: #{SmithyHttpServer}::routers::RoutingService<#{Router}<S>, #{Protocol}>,
@@ -496,7 +430,6 @@ class ServerServiceGeneratorV2(
             "NotSetFields" to notSetFields.join(", "),
             "Router" to protocol.routerType(),
             "Protocol" to protocol.markerStruct(),
-            "Handlers" to handlers,
             *codegenScope,
         )
     }
@@ -536,8 +469,99 @@ class ServerServiceGeneratorV2(
     }
 
     fun render(writer: RustWriter) {
+        val handlers: Writable = operations
+            .map { operation ->
+                DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature()
+            }
+            .reduce { acc, wt ->
+                writable {
+                    rustTemplate("#{acc:W} \n#{wt:W}", "acc" to acc, "wt" to wt)
+                }
+            }
+
         writer.rustTemplate(
             """
+            /// This module contains the implementation of $serviceName.
+            /// [`$serviceName`] is used to set your business logic to implement your [operations],
+            /// customize your [operations]'s behaviors by applying middleware,
+            /// and run your server.
+            ///
+            /// [`$serviceName`] contains the [operations] modeled in your Smithy service.
+            /// You must set an implementation for all operations with the correct signature,
+            /// or your service will fail to be constructed at runtime and panic.
+            /// For each of the [operations] modeled in
+            /// your Smithy service, you need to provide an implementation in the
+            /// form of an async function that takes in the
+            /// operation's input as their first parameter, and returns the
+            /// operation's output. If your operation is fallible (i.e. it
+            /// contains the `errors` member in your Smithy model), the function
+            /// implementing the operation has to be fallible (i.e. return a
+            /// [`Result`]).
+            /// The possible forms for your async functions are:
+            /// ```rust
+            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>;
+            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output;
+            /// ```
+            /// Both can take up to 8 extensions, or none:
+            /// ```rust
+            /// async fn handler_with_no_extensions(input: Input) -> ...;
+            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...;
+            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...;
+            /// ...
+            /// ```
+            /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
+            ///
+            /// To construct [`$serviceName`], you can build:
+            /// * [`$serviceName::builder_without_plugins()`] which returns a [`$builderName`] without any middleware applied.
+            /// * [`$serviceName::builder_with_plugins(plugins)`] which returns a [`$builderName`] that applies `plugins` to all your operations.
+            ///
+            /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
+            ///
+            /// When you have set all your operations, you can convert [`$serviceName`] into a [Service] calling:
+            /// * [`$serviceName::into_make_service`] that converts $serviceName into a type that implements [`tower::make::MakeService`], a _service factory_.
+            /// * [`$serviceName::into_make_service_with_connect_info`] that converts $serviceName into [`tower::make::MakeService`]
+            /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
+            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}Extension`].
+            ///
+            /// You can feed this value to a [Hyper server], and the
+            /// server will instantiate and [`serve`] your service.
+            ///
+            /// Here's a full example to get you started:
+            ///
+            /// ```rust
+            /// use std::net::SocketAddr;
+            /// use ${codegenContext.moduleUseName()}::$serviceName;
+            ///
+            /// ##[tokio::main]
+            /// pub async fn main() {
+            ///    let app = $serviceName::builder_without_plugins()
+            ${builderFieldNames.values.joinToString("\n") { "///        .$it($it)" }}
+            ///        .build()
+            ///        .expect("failed to build an instance of $serviceName");
+            ///
+            ///    let bind: SocketAddr = "127.0.0.1:6969".parse()
+            ///        .expect("unable to parse the server bind address and port");
+            ///
+            ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
+            ///    ## let server = async { Ok::<_, ()>(()) };
+            ///
+            ///    // Run your service!
+            ///    if let Err(err) = server.await {
+            ///      eprintln!("server error: {}", err);
+            ///    }
+            /// }
+            ///
+            #{Handlers:W}
+            ///
+            /// ```
+            ///
+            /// [`serve`]: https://docs.rs/hyper/0.14.16/hyper/server/struct.Builder.html##method.serve
+            /// [`tower::make::MakeService`]: https://docs.rs/tower/latest/tower/make/trait.MakeService.html
+            /// [HTTP binding traits]: https://smithy.io/2.0/spec/http-bindings.html
+            /// [operations]: https://smithy.io/2.0/spec/service-types.html##operation
+            /// [Hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
+            /// [Service]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
+
             #{Builder:W}
 
             #{MissingOperationsError:W}
@@ -550,6 +574,9 @@ class ServerServiceGeneratorV2(
             "MissingOperationsError" to missingOperationsError(),
             "RequestSpecs" to requestSpecsModule(),
             "Struct" to serviceStruct(),
+            "Handlers" to handlers,
+            "ExampleHandler" to operations.take(1).map { operation -> DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature() },
+            *codegenScope,
         )
     }
 }

From 28cfe351f843c553e702d316e4ee388b3d73eec4 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Thu, 24 Nov 2022 15:42:59 +0100
Subject: [PATCH 07/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 30 ++++++++++++-------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 30a492a4a1..0eccb159bd 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -17,6 +17,9 @@ import software.amazon.smithy.rust.codegen.core.rustlang.rust
 import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
 import software.amazon.smithy.rust.codegen.core.rustlang.writable
 import software.amazon.smithy.rust.codegen.core.smithy.CodegenContext
+import software.amazon.smithy.rust.codegen.core.smithy.Errors
+import software.amazon.smithy.rust.codegen.core.smithy.Inputs
+import software.amazon.smithy.rust.codegen.core.smithy.Outputs
 import software.amazon.smithy.rust.codegen.core.util.toPascalCase
 import software.amazon.smithy.rust.codegen.core.util.toSnakeCase
 import software.amazon.smithy.rust.codegen.server.smithy.ServerCargoDependency
@@ -469,6 +472,7 @@ class ServerServiceGeneratorV2(
     }
 
     fun render(writer: RustWriter) {
+        val crateName = codegenContext.moduleUseName()
         val handlers: Writable = operations
             .map { operation ->
                 DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature()
@@ -481,12 +485,17 @@ class ServerServiceGeneratorV2(
 
         writer.rustTemplate(
             """
-            /// This module contains the implementation of $serviceName.
-            /// [`$serviceName`] is used to set your business logic to implement your [operations],
+            /// A fast and customizable Rust implementation of the $serviceName Smithy service.
+            ///
+            /// This crate provides all types required to setup the [`$serviceName`] Service.
+            /// The [`$crateName::${Inputs.namespace}`], [`$crateName::${Outputs.namespace}`], and [`$crateName::${Errors.namespace}`] modules provide the types used in each operation.
+            ///
+            /// The primary export is [`$serviceName`]: it is the
+            /// [`$builderName`] is used to set your business logic to implement your [operations],
             /// customize your [operations]'s behaviors by applying middleware,
-            /// and run your server.
+            /// and build your service.
             ///
-            /// [`$serviceName`] contains the [operations] modeled in your Smithy service.
+            /// [`$builderName`] contains the [operations] modeled in your Smithy service.
             /// You must set an implementation for all operations with the correct signature,
             /// or your service will fail to be constructed at runtime and panic.
             /// For each of the [operations] modeled in
@@ -495,8 +504,7 @@ class ServerServiceGeneratorV2(
             /// operation's input as their first parameter, and returns the
             /// operation's output. If your operation is fallible (i.e. it
             /// contains the `errors` member in your Smithy model), the function
-            /// implementing the operation has to be fallible (i.e. return a
-            /// [`Result`]).
+            /// implementing the operation has to be fallible (i.e. return a [`Result`]).
             /// The possible forms for your async functions are:
             /// ```rust
             /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>;
@@ -511,26 +519,26 @@ class ServerServiceGeneratorV2(
             /// ```
             /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
             ///
-            /// To construct [`$serviceName`], you can build:
-            /// * [`$serviceName::builder_without_plugins()`] which returns a [`$builderName`] without any middleware applied.
+            /// To construct [`$serviceName`], you can use:
+            /// * [`$serviceName::builder_without_plugins()`] which returns a [`$builderName`] without any service-wide middleware applied.
             /// * [`$serviceName::builder_with_plugins(plugins)`] which returns a [`$builderName`] that applies `plugins` to all your operations.
             ///
             /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
             ///
-            /// When you have set all your operations, you can convert [`$serviceName`] into a [Service] calling:
+            /// When you have set all your operations, you can convert [`$serviceName`] into a tower [Service] calling:
             /// * [`$serviceName::into_make_service`] that converts $serviceName into a type that implements [`tower::make::MakeService`], a _service factory_.
             /// * [`$serviceName::into_make_service_with_connect_info`] that converts $serviceName into [`tower::make::MakeService`]
             /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
             /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}Extension`].
             ///
-            /// You can feed this value to a [Hyper server], and the
+            /// You can feed this [Service] to a [Hyper server], and the
             /// server will instantiate and [`serve`] your service.
             ///
             /// Here's a full example to get you started:
             ///
             /// ```rust
             /// use std::net::SocketAddr;
-            /// use ${codegenContext.moduleUseName()}::$serviceName;
+            /// use $crateName::$serviceName;
             ///
             /// ##[tokio::main]
             /// pub async fn main() {

From c6e321df2eef66af369902519660c08b5dc53109 Mon Sep 17 00:00:00 2001
From: Daniele Ahmed <ahmeddan@amazon.de>
Date: Thu, 24 Nov 2022 17:06:30 +0100
Subject: [PATCH 08/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../smithy/generators/ServerServiceGeneratorV2.kt    | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 0eccb159bd..fc12089c9e 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -483,12 +483,16 @@ class ServerServiceGeneratorV2(
                 }
             }
 
+        val hasErrors = service.errors.isNotEmpty()
+
         writer.rustTemplate(
             """
             /// A fast and customizable Rust implementation of the $serviceName Smithy service.
             ///
-            /// This crate provides all types required to setup the [`$serviceName`] Service.
-            /// The [`$crateName::${Inputs.namespace}`], [`$crateName::${Outputs.namespace}`], and [`$crateName::${Errors.namespace}`] modules provide the types used in each operation.
+            /// The primary export is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
+            /// trait and therefore can be handed to [`Hyper server`] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
+            /// The [`crate::${Inputs.namespace}`], ${if (hasErrors) "and " else ""}[`crate::${Outputs.namespace}`], ${if (!hasErrors) "and [`crate::${Errors.namespace}`]" else "" }
+            /// modules provide the types used in each operation.
             ///
             /// The primary export is [`$serviceName`]: it is the
             /// [`$builderName`] is used to set your business logic to implement your [operations],
@@ -520,8 +524,8 @@ class ServerServiceGeneratorV2(
             /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
             ///
             /// To construct [`$serviceName`], you can use:
-            /// * [`$serviceName::builder_without_plugins()`] which returns a [`$builderName`] without any service-wide middleware applied.
-            /// * [`$serviceName::builder_with_plugins(plugins)`] which returns a [`$builderName`] that applies `plugins` to all your operations.
+            /// * [`$serviceName::builder_without_plugins`] which returns a [`$builderName`] without any service-wide middleware applied.
+            /// * [`$serviceName::builder_with_plugins`] which returns a [`$builderName`] that applies `plugins` to all your operations.
             ///
             /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
             ///

From bb75fded4fba01dcb7c9f3fd7b041a8026849d9c Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Thu, 24 Nov 2022 17:21:28 +0100
Subject: [PATCH 09/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../smithy/generators/ServerServiceGeneratorV2.kt  | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index fc12089c9e..cf3c0a41e8 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -483,15 +483,15 @@ class ServerServiceGeneratorV2(
                 }
             }
 
-        val hasErrors = service.errors.isNotEmpty()
+        val hasErrors = service.operations.any { model.expectShape(it).asOperationShape().get().errors.isNotEmpty() }
 
         writer.rustTemplate(
             """
             /// A fast and customizable Rust implementation of the $serviceName Smithy service.
             ///
             /// The primary export is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
-            /// trait and therefore can be handed to [`Hyper server`] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
-            /// The [`crate::${Inputs.namespace}`], ${if (hasErrors) "and " else ""}[`crate::${Outputs.namespace}`], ${if (!hasErrors) "and [`crate::${Errors.namespace}`]" else "" }
+            /// trait and therefore can be handed to [Hyper server] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
+            /// The [`crate::${Inputs.namespace}`], ${if (!hasErrors) "and " else ""}[`crate::${Outputs.namespace}`], ${if (hasErrors) "and [`crate::${Errors.namespace}`]" else "" }
             /// modules provide the types used in each operation.
             ///
             /// The primary export is [`$serviceName`]: it is the
@@ -511,14 +511,14 @@ class ServerServiceGeneratorV2(
             /// implementing the operation has to be fallible (i.e. return a [`Result`]).
             /// The possible forms for your async functions are:
             /// ```rust
-            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>;
-            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output;
+            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>
+            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output
             /// ```
             /// Both can take up to 8 extensions, or none:
             /// ```rust
             /// async fn handler_with_no_extensions(input: Input) -> ...;
-            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...;
-            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...;
+            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...
+            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...
             /// ...
             /// ```
             /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.

From 22609088c94b1aea48035c167761b952f4de6218 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Thu, 24 Nov 2022 17:27:43 +0100
Subject: [PATCH 10/23] Update dependencies

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index cf3c0a41e8..aa702d590e 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -17,9 +17,9 @@ import software.amazon.smithy.rust.codegen.core.rustlang.rust
 import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
 import software.amazon.smithy.rust.codegen.core.rustlang.writable
 import software.amazon.smithy.rust.codegen.core.smithy.CodegenContext
-import software.amazon.smithy.rust.codegen.core.smithy.Errors
-import software.amazon.smithy.rust.codegen.core.smithy.Inputs
-import software.amazon.smithy.rust.codegen.core.smithy.Outputs
+import software.amazon.smithy.rust.codegen.core.smithy.ErrorsModule
+import software.amazon.smithy.rust.codegen.core.smithy.InputsModule
+import software.amazon.smithy.rust.codegen.core.smithy.OutputsModule
 import software.amazon.smithy.rust.codegen.core.util.toPascalCase
 import software.amazon.smithy.rust.codegen.core.util.toSnakeCase
 import software.amazon.smithy.rust.codegen.server.smithy.ServerCargoDependency
@@ -491,7 +491,7 @@ class ServerServiceGeneratorV2(
             ///
             /// The primary export is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
             /// trait and therefore can be handed to [Hyper server] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
-            /// The [`crate::${Inputs.namespace}`], ${if (!hasErrors) "and " else ""}[`crate::${Outputs.namespace}`], ${if (hasErrors) "and [`crate::${Errors.namespace}`]" else "" }
+            /// The [`crate::${InputsModule.name}`], ${if (!hasErrors) "and " else ""}[`crate::${OutputsModule.name}`], ${if (hasErrors) "and [`crate::${ErrorsModule.name}`]" else "" }
             /// modules provide the types used in each operation.
             ///
             /// The primary export is [`$serviceName`]: it is the

From 566d12a08ab776ae64ad8bb273196721a258e8e1 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Fri, 25 Nov 2022 10:49:40 +0100
Subject: [PATCH 11/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index aa702d590e..d03b4c4ca2 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -510,12 +510,12 @@ class ServerServiceGeneratorV2(
             /// contains the `errors` member in your Smithy model), the function
             /// implementing the operation has to be fallible (i.e. return a [`Result`]).
             /// The possible forms for your async functions are:
-            /// ```rust
+            /// ```rust,no_run
             /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>
             /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output
             /// ```
             /// Both can take up to 8 extensions, or none:
-            /// ```rust
+            /// ```rust,no_run
             /// async fn handler_with_no_extensions(input: Input) -> ...;
             /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...
             /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...

From 0a943c634223de88faf83d8616f5b8c5bb5f1dd4 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Fri, 25 Nov 2022 10:57:57 +0100
Subject: [PATCH 12/23] Update docs

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../smithy/generators/ServerServiceGeneratorV2.kt      | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index d03b4c4ca2..05f37c67c1 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -511,14 +511,14 @@ class ServerServiceGeneratorV2(
             /// implementing the operation has to be fallible (i.e. return a [`Result`]).
             /// The possible forms for your async functions are:
             /// ```rust,no_run
-            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>
-            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output
+            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Result<Output, Error>
+            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output
             /// ```
             /// Both can take up to 8 extensions, or none:
             /// ```rust,no_run
             /// async fn handler_with_no_extensions(input: Input) -> ...;
-            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...
-            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...
+            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}::Extension<T>) -> ...
+            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}::Extension<T>, ext1: #{SmithyHttpServer}::Extension<T>) -> ...
             /// ...
             /// ```
             /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
@@ -533,7 +533,7 @@ class ServerServiceGeneratorV2(
             /// * [`$serviceName::into_make_service`] that converts $serviceName into a type that implements [`tower::make::MakeService`], a _service factory_.
             /// * [`$serviceName::into_make_service_with_connect_info`] that converts $serviceName into [`tower::make::MakeService`]
             /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
-            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}Extension`].
+            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}::Extension`].
             ///
             /// You can feed this [Service] to a [Hyper server], and the
             /// server will instantiate and [`serve`] your service.

From f687d5d04e9caf652871dbd8bd9997ceb3ef769a Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Tue, 29 Nov 2022 17:23:07 +0100
Subject: [PATCH 13/23] Address comments

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 97 ++++++++++++-------
 1 file changed, 60 insertions(+), 37 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 05f37c67c1..57c8e768f8 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -489,56 +489,79 @@ class ServerServiceGeneratorV2(
             """
             /// A fast and customizable Rust implementation of the $serviceName Smithy service.
             ///
+            /// ## Using the $serviceName
+            ///
             /// The primary export is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
             /// trait and therefore can be handed to [Hyper server] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
             /// The [`crate::${InputsModule.name}`], ${if (!hasErrors) "and " else ""}[`crate::${OutputsModule.name}`], ${if (hasErrors) "and [`crate::${ErrorsModule.name}`]" else "" }
             /// modules provide the types used in each operation.
             ///
-            /// The primary export is [`$serviceName`]: it is the
-            /// [`$builderName`] is used to set your business logic to implement your [operations],
-            /// customize your [operations]'s behaviors by applying middleware,
-            /// and build your service.
-            ///
-            /// [`$builderName`] contains the [operations] modeled in your Smithy service.
-            /// You must set an implementation for all operations with the correct signature,
-            /// or your service will fail to be constructed at runtime and panic.
-            /// For each of the [operations] modeled in
-            /// your Smithy service, you need to provide an implementation in the
-            /// form of an async function that takes in the
-            /// operation's input as their first parameter, and returns the
-            /// operation's output. If your operation is fallible (i.e. it
-            /// contains the `errors` member in your Smithy model), the function
-            /// implementing the operation has to be fallible (i.e. return a [`Result`]).
-            /// The possible forms for your async functions are:
-            /// ```rust,no_run
-            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Result<Output, Error>
-            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output
+            /// ###### Running on Hyper
+            /// ```no_run
+            /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
+            /// let server = app.into_make_service();
+            /// hyper::Server::bind(&bind).serve(server).await.unwrap();
             /// ```
-            /// Both can take up to 8 extensions, or none:
-            /// ```rust,no_run
-            /// async fn handler_with_no_extensions(input: Input) -> ...;
-            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}::Extension<T>) -> ...
-            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}::Extension<T>, ext1: #{SmithyHttpServer}::Extension<T>) -> ...
-            /// ...
+            /// ###### Running on Lambda
+            /// ```no_run
+            /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
+            /// let handler = #{SmithyHttpServer}::routing::LambdaHandler::new(app);
+            /// lambda_http::run(handler).await.unwrap();
             /// ```
-            /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
             ///
-            /// To construct [`$serviceName`], you can use:
-            /// * [`$serviceName::builder_without_plugins`] which returns a [`$builderName`] without any service-wide middleware applied.
-            /// * [`$serviceName::builder_with_plugins`] which returns a [`$builderName`] that applies `plugins` to all your operations.
+            /// ## Building the $serviceName
+            ///
+            /// To construct [`$serviceName`] we use [`$builderName`] returned by [`$serviceName::builder_without_plugins`]
+            /// or [`$serviceName::builder_with_plugins`].
+            ///
+            /// #### Plugins
+            ///
+            /// The [`$serviceName::builder_with_plugins`] method, returning [`$builderName`], we saw earlier,
+            /// accepts a `plugin`. Plugins allow you to build middleware which is aware of the operation it is being applied to.
+            ///
+            /// ```rust,no_run
+            /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as LoggingPlugin;
+            /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as MetricsPlugin;
+            /// let plugins = PluginPipeline::new()
+            ///         .push(LoggingPlugin)
+            ///         .push(MetricsPlugin);
+            /// let builder = $serviceName::builder_with_plugins(plugins);
+            /// ```
             ///
             /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
             ///
-            /// When you have set all your operations, you can convert [`$serviceName`] into a tower [Service] calling:
-            /// * [`$serviceName::into_make_service`] that converts $serviceName into a type that implements [`tower::make::MakeService`], a _service factory_.
-            /// * [`$serviceName::into_make_service_with_connect_info`] that converts $serviceName into [`tower::make::MakeService`]
-            /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
-            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}::Extension`].
+            /// #### Handlers
+            ///
+            /// For each operation it has an associated setters accepting an async function conforming to the Smithy model.
+            /// The async functions, or "handlers", contain the business logic of your application.
+            ///
+            /// Every handler must take an `Input`, and optional [`extractor arguments`](#{SmithyHttpServer}::request), while return:
+            ///
+            /// * A `Result<Output, Error>` if your operation has modeled errors, or
+            /// * An `Output` otherwise.
+            ///
+            /// ```rust,ignore
+            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Result<Output, Error> { todo!() }
+            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output { todo!() }
+            /// ```
+            ///
+            /// Handlers accept up to 8 extractors:
+            ///
+            /// ```rust,ignore
+            /// async fn handler_with_no_extensions(input: Input) -> ... { todo!() }
+            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}::Extension<T>) -> ... { todo!() }
+            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}::Extension<T>, ext1: #{SmithyHttpServer}::Extension<T>) -> ... { todo!() }
+            /// ...
+            /// ```
+            ///
+            /// #### Build
+            ///
+            /// When you have set all your operations, you can construct [`$serviceName`] using:
             ///
-            /// You can feed this [Service] to a [Hyper server], and the
-            /// server will instantiate and [`serve`] your service.
+            /// * [`$builderName::build`]: a fallible constructor, returning an error describing the missing operations
+            /// * [`$builderName::build_unchecked`]: an infallible constructor, returning a 500 when requesting missing operations
             ///
-            /// Here's a full example to get you started:
+            /// ## Example
             ///
             /// ```rust
             /// use std::net::SocketAddr;

From 78cc474a59f2689b4a05e651e210b76c7e89483e Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 12:37:34 +0100
Subject: [PATCH 14/23] Address comments

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 57c8e768f8..e3338c5cf2 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -516,8 +516,9 @@ class ServerServiceGeneratorV2(
             ///
             /// #### Plugins
             ///
-            /// The [`$serviceName::builder_with_plugins`] method, returning [`$builderName`], we saw earlier,
-            /// accepts a `plugin`. Plugins allow you to build middleware which is aware of the operation it is being applied to.
+            /// The [`$serviceName::builder_with_plugins`] method, returning [`$builderName`],
+            /// accepts a [`Plugin`](aws_smithy_http_server::plugin::Plugin).
+            /// Plugins allow you to build middleware which is aware of the operation it is being applied to.
             ///
             /// ```rust,no_run
             /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as LoggingPlugin;
@@ -532,10 +533,10 @@ class ServerServiceGeneratorV2(
             ///
             /// #### Handlers
             ///
-            /// For each operation it has an associated setters accepting an async function conforming to the Smithy model.
+            /// For each operation [`$builderName`] has an associated setter accepting an async function conforming to the Smithy model.
             /// The async functions, or "handlers", contain the business logic of your application.
             ///
-            /// Every handler must take an `Input`, and optional [`extractor arguments`](#{SmithyHttpServer}::request), while return:
+            /// Every handler must take an `Input`, and optional [`extractor arguments`](#{SmithyHttpServer}::request), while returning:
             ///
             /// * A `Result<Output, Error>` if your operation has modeled errors, or
             /// * An `Output` otherwise.

From 28f182f02f1ec3533bafec91038b18e833a6501e Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 12:43:54 +0100
Subject: [PATCH 15/23] Fix CI

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index e3338c5cf2..8d00351180 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -498,15 +498,21 @@ class ServerServiceGeneratorV2(
             ///
             /// ###### Running on Hyper
             /// ```no_run
+            /// ## use $crateName::$serviceName;
+            /// ## pub async fn main() {
             /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
             /// let server = app.into_make_service();
             /// hyper::Server::bind(&bind).serve(server).await.unwrap();
+            /// ## }
             /// ```
             /// ###### Running on Lambda
             /// ```no_run
+            /// ## use $crateName::$serviceName;
+            /// ## pub async fn main() {
             /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
             /// let handler = #{SmithyHttpServer}::routing::LambdaHandler::new(app);
             /// lambda_http::run(handler).await.unwrap();
+            /// ## }
             /// ```
             ///
             /// ## Building the $serviceName
@@ -526,7 +532,7 @@ class ServerServiceGeneratorV2(
             /// let plugins = PluginPipeline::new()
             ///         .push(LoggingPlugin)
             ///         .push(MetricsPlugin);
-            /// let builder = $serviceName::builder_with_plugins(plugins);
+            /// let builder = $crateName::$serviceName::builder_with_plugins(plugins);
             /// ```
             ///
             /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
@@ -577,7 +583,6 @@ class ServerServiceGeneratorV2(
             ///
             ///    let bind: SocketAddr = "127.0.0.1:6969".parse()
             ///        .expect("unable to parse the server bind address and port");
-            ///
             ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
             ///    ## let server = async { Ok::<_, ()>(()) };
             ///

From 9e3bf62216551ba4eca6b8de50baa6127102b69e Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 12:47:11 +0100
Subject: [PATCH 16/23] Fix CI

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt       | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 8d00351180..d861618f38 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -529,6 +529,7 @@ class ServerServiceGeneratorV2(
             /// ```rust,no_run
             /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as LoggingPlugin;
             /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as MetricsPlugin;
+            /// ## use #{SmithyHttpServer}::plugin::PluginPipeline;
             /// let plugins = PluginPipeline::new()
             ///         .push(LoggingPlugin)
             ///         .push(MetricsPlugin);
@@ -588,7 +589,7 @@ class ServerServiceGeneratorV2(
             ///
             ///    // Run your service!
             ///    if let Err(err) = server.await {
-            ///      eprintln!("server error: {}", err);
+            ///      eprintln!("server error: {:?}", err);
             ///    }
             /// }
             ///

From bc9e5bd742db0ad7310cc4ab7a9a3a140142a86d Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 14:05:00 +0100
Subject: [PATCH 17/23] Fix CI

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt      | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index d861618f38..482d0a8156 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -499,15 +499,19 @@ class ServerServiceGeneratorV2(
             /// ###### Running on Hyper
             /// ```no_run
             /// ## use $crateName::$serviceName;
+            /// ## ##[tokio::main]
             /// ## pub async fn main() {
             /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
             /// let server = app.into_make_service();
+            /// let bind: SocketAddr = "127.0.0.1:6969".parse()
+            ///     .expect("unable to parse the server bind address and port");
             /// hyper::Server::bind(&bind).serve(server).await.unwrap();
             /// ## }
             /// ```
             /// ###### Running on Lambda
             /// ```no_run
             /// ## use $crateName::$serviceName;
+            /// ## ##[tokio::main]
             /// ## pub async fn main() {
             /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
             /// let handler = #{SmithyHttpServer}::routing::LambdaHandler::new(app);

From 8faff7dde7c0ecee7133a231a334f6132c7e57b2 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 14:49:12 +0100
Subject: [PATCH 18/23] Fix CI

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt   | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 482d0a8156..9b6a490b7c 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -497,8 +497,9 @@ class ServerServiceGeneratorV2(
             /// modules provide the types used in each operation.
             ///
             /// ###### Running on Hyper
-            /// ```no_run
+            /// ```rust,no_run
             /// ## use $crateName::$serviceName;
+            /// ## use std::net::SocketAddr;
             /// ## ##[tokio::main]
             /// ## pub async fn main() {
             /// ## let app = $serviceName::builder_without_plugins().build_unchecked();
@@ -509,7 +510,7 @@ class ServerServiceGeneratorV2(
             /// ## }
             /// ```
             /// ###### Running on Lambda
-            /// ```no_run
+            /// ```rust,ignore
             /// ## use $crateName::$serviceName;
             /// ## ##[tokio::main]
             /// ## pub async fn main() {
@@ -530,7 +531,7 @@ class ServerServiceGeneratorV2(
             /// accepts a [`Plugin`](aws_smithy_http_server::plugin::Plugin).
             /// Plugins allow you to build middleware which is aware of the operation it is being applied to.
             ///
-            /// ```rust,no_run
+            /// ```rust,ignore
             /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as LoggingPlugin;
             /// ## use #{SmithyHttpServer}::plugin::IdentityPlugin as MetricsPlugin;
             /// ## use #{SmithyHttpServer}::plugin::PluginPipeline;

From 9ec3ad34eadf74ad7da07888d7385ac58c019c73 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 16:00:38 +0100
Subject: [PATCH 19/23] Address comments

Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
---
 .../generators/ServerServiceGeneratorV2.kt    | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 9b6a490b7c..8041ed1c73 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -489,10 +489,10 @@ class ServerServiceGeneratorV2(
             """
             /// A fast and customizable Rust implementation of the $serviceName Smithy service.
             ///
-            /// ## Using the $serviceName
+            /// ## Using $serviceName
             ///
-            /// The primary export is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
-            /// trait and therefore can be handed to [Hyper server] using [`$serviceName::into_make_service`] or used in Lambda using [`#{SmithyHttpServer}::routing::LambdaHandler`].
+            /// The primary entrypoint is [`$serviceName`]: it satisfies the [`Service<http::Request, Response = http::Response>`]
+            /// trait and therefore can be handed to a [`hyper` server] via [`$serviceName::into_make_service`] or used in Lambda via [`#{SmithyHttpServer}::routing::LambdaHandler`].
             /// The [`crate::${InputsModule.name}`], ${if (!hasErrors) "and " else ""}[`crate::${OutputsModule.name}`], ${if (hasErrors) "and [`crate::${ErrorsModule.name}`]" else "" }
             /// modules provide the types used in each operation.
             ///
@@ -546,7 +546,7 @@ class ServerServiceGeneratorV2(
             /// #### Handlers
             ///
             /// For each operation [`$builderName`] has an associated setter accepting an async function conforming to the Smithy model.
-            /// The async functions, or "handlers", contain the business logic of your application.
+            /// We call these async functions **handlers**. This is where your application business logic lives.
             ///
             /// Every handler must take an `Input`, and optional [`extractor arguments`](#{SmithyHttpServer}::request), while returning:
             ///
@@ -554,8 +554,8 @@ class ServerServiceGeneratorV2(
             /// * An `Output` otherwise.
             ///
             /// ```rust,ignore
-            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Result<Output, Error> { todo!() }
-            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output { todo!() }
+            /// async fn fallible_handler(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Result<Output, Error> { todo!() }
+            /// async fn infallible_handler(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output { todo!() }
             /// ```
             ///
             /// Handlers accept up to 8 extractors:
@@ -569,10 +569,10 @@ class ServerServiceGeneratorV2(
             ///
             /// #### Build
             ///
-            /// When you have set all your operations, you can construct [`$serviceName`] using:
+            /// When you have set all the operations you want to serve, you can construct [`$serviceName`] using:
             ///
-            /// * [`$builderName::build`]: a fallible constructor, returning an error describing the missing operations
-            /// * [`$builderName::build_unchecked`]: an infallible constructor, returning a 500 when requesting missing operations
+            /// * [`$builderName::build`]: a fallible constructor, returning an error describing the missing operations from all possible ones in the Smithy model
+            /// * [`$builderName::build_unchecked`]: an infallible constructor, returning a 500 when requesting missing, unset operations
             ///
             /// ## Example
             ///
@@ -606,7 +606,7 @@ class ServerServiceGeneratorV2(
             /// [`tower::make::MakeService`]: https://docs.rs/tower/latest/tower/make/trait.MakeService.html
             /// [HTTP binding traits]: https://smithy.io/2.0/spec/http-bindings.html
             /// [operations]: https://smithy.io/2.0/spec/service-types.html##operation
-            /// [Hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
+            /// [hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
             /// [Service]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
 
             #{Builder:W}

From f2f83dfd88241476ff2a5d8dc8acdb98f7ca2085 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 15:15:13 +0000
Subject: [PATCH 20/23] Update
 codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

Co-authored-by: Luca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 8041ed1c73..2ba9440d34 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -541,7 +541,7 @@ class ServerServiceGeneratorV2(
             /// let builder = $crateName::$serviceName::builder_with_plugins(plugins);
             /// ```
             ///
-            /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
+            /// Check out [`#{SmithyHttpServer}::plugin`] to learn more about plugins.
             ///
             /// #### Handlers
             ///

From 90fca461f19bb539a1ad64cc3d42af8547c0a76e Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 15:25:18 +0000
Subject: [PATCH 21/23] Update
 codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

Co-authored-by: Luca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 2ba9440d34..dbea2ebd68 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -558,7 +558,7 @@ class ServerServiceGeneratorV2(
             /// async fn infallible_handler(input: Input, extensions: #{SmithyHttpServer}::Extension<T>) -> Output { todo!() }
             /// ```
             ///
-            /// Handlers accept up to 8 extractors:
+            /// Handlers can accept up to 8 extractors:
             ///
             /// ```rust,ignore
             /// async fn handler_with_no_extensions(input: Input) -> ... { todo!() }

From 43b45dd380ee1f52932108f64f04b65ef0e22583 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 15:25:28 +0000
Subject: [PATCH 22/23] Update
 codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

Co-authored-by: Luca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt  | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index dbea2ebd68..98c70bbe94 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -569,10 +569,12 @@ class ServerServiceGeneratorV2(
             ///
             /// #### Build
             ///
-            /// When you have set all the operations you want to serve, you can construct [`$serviceName`] using:
+            /// You can convert [`$builderName`] into [`$serviceName`] using either [`$builderName::build`] or [`$builderName::build_unchecked`].  
             ///
-            /// * [`$builderName::build`]: a fallible constructor, returning an error describing the missing operations from all possible ones in the Smithy model
-            /// * [`$builderName::build_unchecked`]: an infallible constructor, returning a 500 when requesting missing, unset operations
+            /// [`$builderName::build`] requires you to provide a handler for every single operation in your Smithy model. It will return an error if that is not the case.  
+            ///
+            /// [`$builderName::build_unchecked`], instead, does not require exhaustiveness. The server will automatically return 500s to all requests for operations that do not have a registered handler.  
+            /// [`$builderName::build_unchecked`] is particularly useful if you are deploying your Smithy service as a collection of Lambda functions, where each Lambda is only responsible for a subset of the operations in the Smithy service (or even a single one!).
             ///
             /// ## Example
             ///

From be9335b772bd8ef9126a712641e5a4ba55a0ce24 Mon Sep 17 00:00:00 2001
From: 82marbag <69267416+82marbag@users.noreply.github.com>
Date: Wed, 30 Nov 2022 15:25:46 +0000
Subject: [PATCH 23/23] Update
 codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

Co-authored-by: Luca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>
---
 .../server/smithy/generators/ServerServiceGeneratorV2.kt        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
index 98c70bbe94..98a754cd53 100644
--- a/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
+++ b/codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt
@@ -545,7 +545,7 @@ class ServerServiceGeneratorV2(
             ///
             /// #### Handlers
             ///
-            /// For each operation [`$builderName`] has an associated setter accepting an async function conforming to the Smithy model.
+            /// [`$builderName`] provides a setter method for each operation in your Smithy model. The setter methods expect an async function as input, matching the signature for the corresponding operation in your Smithy model.
             /// We call these async functions **handlers**. This is where your application business logic lives.
             ///
             /// Every handler must take an `Input`, and optional [`extractor arguments`](#{SmithyHttpServer}::request), while returning: