From a738aa225d15dcaa6a3edb8308c2ccb0ee1bd32b Mon Sep 17 00:00:00 2001
From: Russell Cohen <rcoh@amazon.com>
Date: Thu, 21 Sep 2023 12:22:50 -0400
Subject: [PATCH 1/2] Generate better docs when fields are required

---
 .../generators/client/FluentClientGenerator.kt    |  2 +-
 .../core/smithy/generators/BuilderGenerator.kt    | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/client/FluentClientGenerator.kt b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/client/FluentClientGenerator.kt
index b2927dca8e..cd50393a92 100644
--- a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/client/FluentClientGenerator.kt
+++ b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/client/FluentClientGenerator.kt
@@ -528,7 +528,7 @@ private fun generateOperationShapeDocs(
             else -> "(undocumented)"
         }
 
-        "[`$builderInputDoc`]($builderInputLink) / [`$builderSetterDoc`]($builderSetterLink): $docs"
+        "[`$builderInputDoc`]($builderInputLink) / [`$builderSetterDoc`]($builderSetterLink):<br>required: **${memberShape.isRequired}**<br>$docs<br>"
     }
 }
 
diff --git a/codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt b/codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt
index 26a607f497..80b9329d63 100644
--- a/codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt
+++ b/codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt
@@ -186,6 +186,14 @@ class BuilderGenerator(
             false -> implBlockWriter.format(outputSymbol)
         }
         implBlockWriter.docs("Consumes the builder and constructs a #D.", outputSymbol)
+        val trulyRequiredMembers = members.filter { trulyRequired(it) }
+        if (trulyRequiredMembers.isNotEmpty()) {
+            implBlockWriter.docs("This method will fail if any of the following fields are not set:")
+            trulyRequiredMembers.forEach {
+                val memberName = symbolProvider.toMemberName(it)
+                implBlockWriter.docs("- [`$memberName`](#T::$memberName)", symbolProvider.symbolForBuilder(shape))
+            }
+        }
         implBlockWriter.rustBlockTemplate("pub fn build(self) -> $returnType", *preludeScope) {
             conditionalBlockTemplate("#{Ok}(", ")", conditional = fallibleBuilder, *preludeScope) {
                 // If a wrapper is specified, use the `::new` associated function to construct the wrapper
@@ -216,6 +224,9 @@ class BuilderGenerator(
         val input = coreType.asArgument("input")
 
         writer.documentShape(member, model)
+        if (member.isRequired) {
+            writer.docs("This field is required.")
+        }
         writer.deprecatedShape(member)
         writer.rustBlock("pub fn $memberName(mut self, ${input.argument}) -> Self") {
             rustTemplate("self.$memberName = #{Some}(${input.value});", *preludeScope)
@@ -369,6 +380,10 @@ class BuilderGenerator(
         }
     }
 
+    private fun trulyRequired(member: MemberShape) = symbolProvider.toSymbol(member).let {
+        !it.isOptional() && !it.canUseDefault()
+    }
+
     /**
      * The core builder of the inner type. If the structure requires a fallible builder, this may use `?` to return
      * errors.

From 530cd3857345fbd8cf1b8d5595bcc06c7920a3ab Mon Sep 17 00:00:00 2001
From: Russell Cohen <rcoh@amazon.com>
Date: Fri, 22 Sep 2023 15:42:41 -0400
Subject: [PATCH 2/2] Changelog

---
 CHANGELOG.next.toml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.next.toml b/CHANGELOG.next.toml
index b08ebefd4e..afb23e8029 100644
--- a/CHANGELOG.next.toml
+++ b/CHANGELOG.next.toml
@@ -14,7 +14,7 @@
 [[smithy-rs]]
 message = "It's now possible to nest runtime components with the `RuntimePlugin` trait. A `current_components` argument was added to the `runtime_components` method so that components configured from previous runtime plugins can be referenced in the current runtime plugin. Ordering of runtime plugins was also introduced via a new `RuntimePlugin::order` method."
 references = ["smithy-rs#2909"]
-meta = { "breaking" = true, "tada" = false, "bug" = false, "target" = "client"}
+meta = { "breaking" = true, "tada" = false, "bug" = false, "target" = "client" }
 author = "jdisanti"
 
 [[aws-sdk-rust]]
@@ -177,3 +177,9 @@ message = "Source defaults from the default trait instead of implicitly based on
 references = ["smithy-rs#2985"]
 meta = { "breaking" = false, "tada" = false, "bug" = true, "target" = "client" }
 author = "rcoh"
+
+[[smithy-rs]]
+message = "Produce better docs when items are marked @required"
+references = ["smithy-rs#2996"]
+meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" }
+author = "rcoh"