Generate better docs when fields are required

smithy-lang · Sep 21, 2023 · b0bd5d8 · b0bd5d8
1 parent 1771dbd
commit b0bd5d8
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 1 deletion.
diff --git a/...tware/amazon/smithy/rust/codegen/client/smithy/generators/client/FluentClientGenerator.kt b/...tware/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/...ain/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt b/...ain/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt
@@ -184,6 +184,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
@@ -214,6 +222,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)
@@ -367,6 +378,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.