From 377e0d621ca086ad550abb0bc72b667a2c62adf7 Mon Sep 17 00:00:00 2001 From: Ritvik Kapila Date: Mon, 10 Feb 2025 14:57:10 -0800 Subject: [PATCH 1/2] feat(go-doc): Add smithy-model API documentation for Go --- .../smithygo/codegen/CodegenUtils.java | 18 ++++++++++++++++++ .../smithygo/codegen/StructureGenerator.java | 3 +++ 2 files changed, 21 insertions(+) diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java index aef04700fa..148431dce2 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java @@ -27,6 +27,7 @@ import java.util.function.Predicate; import java.util.logging.Logger; import software.amazon.polymorph.smithygo.codegen.knowledge.GoPointableIndex; +import software.amazon.polymorph.utils.ModelUtils; import software.amazon.smithy.codegen.core.CodegenException; import software.amazon.smithy.codegen.core.Symbol; import software.amazon.smithy.codegen.core.SymbolProvider; @@ -460,4 +461,21 @@ public static boolean isNumber(Shape shape) { return false; } } + + /** + * docFromShapeEmpty returns the documentation string from the smithy-model if it exists + * + * @param shape shape to get documentation + * @return doc string + */ + protected static String docFromShape(Shape shape) { + Optional maybeDoc = ModelUtils.getDocumentationOrJavadoc(shape); + if (maybeDoc.isPresent()) { + return ( + "//\n// " + String.join("\n// ", maybeDoc.get().split("\\r?\\n")) + ); + } else { + return "//"; + } + } } diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java index c0386f9758..ee1b9055a1 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java @@ -16,6 +16,7 @@ package software.amazon.polymorph.smithygo.codegen; import java.util.HashSet; +import java.util.Optional; import java.util.Set; import software.amazon.polymorph.smithygo.localservice.nameresolver.DafnyNameResolver; import software.amazon.polymorph.smithygo.localservice.nameresolver.SmithyNameResolver; @@ -25,6 +26,7 @@ import software.amazon.smithy.codegen.core.SymbolProvider; import software.amazon.smithy.model.Model; import software.amazon.smithy.model.shapes.MemberShape; +import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.StructureShape; import software.amazon.smithy.model.traits.ErrorTrait; import software.amazon.smithy.model.traits.StreamingTrait; @@ -90,6 +92,7 @@ public void renderStructure(Runnable runnable) { public void renderStructure(Runnable runnable, boolean isInputStructure) { writer.addImport("fmt"); Symbol symbol = symbolProvider.toSymbol(shape); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer.openBlock("type $L struct {", symbol.getName()); CodegenUtils.SortedMembers sortedMembers = new CodegenUtils.SortedMembers( symbolProvider From 27cfbb30a6d66545f469a569596e3672cf31e7a2 Mon Sep 17 00:00:00 2001 From: Ritvik Kapila Date: Mon, 10 Feb 2025 16:32:52 -0800 Subject: [PATCH 2/2] m --- .../amazon/polymorph/smithygo/codegen/CodegenUtils.java | 3 ++- .../amazon/polymorph/smithygo/codegen/EnumGenerator.java | 3 +++ .../amazon/polymorph/smithygo/codegen/IntEnumGenerator.java | 1 + .../amazon/polymorph/smithygo/codegen/StructureGenerator.java | 2 ++ .../amazon/polymorph/smithygo/codegen/UnionGenerator.java | 3 +++ .../amazon/polymorph/smithygo/codegen/ValidationGenerator.java | 1 + 6 files changed, 12 insertions(+), 1 deletion(-) diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java index 148431dce2..64c9946cc8 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/CodegenUtils.java @@ -472,9 +472,10 @@ protected static String docFromShape(Shape shape) { Optional maybeDoc = ModelUtils.getDocumentationOrJavadoc(shape); if (maybeDoc.isPresent()) { return ( - "//\n// " + String.join("\n// ", maybeDoc.get().split("\\r?\\n")) + "// " + String.join("\n// ", maybeDoc.get().split("\\r?\\n")) ); } else { + // Don't create a documentation string if the smithy model doesn't have one return "//"; } } diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/EnumGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/EnumGenerator.java index f86ec20ccf..5409bd695d 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/EnumGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/EnumGenerator.java @@ -63,6 +63,7 @@ public void run() { // a name. if (enumTrait.getValues().get(0).getName().isPresent()) { Set constants = new LinkedHashSet<>(); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer .openBlock( "const (", @@ -110,12 +111,14 @@ public void run() { .write(""); } + writer.openBlock(CodegenUtils.docFromShape(shape)); writer.openBlock( "func ($L) Values() []$L {", "}", symbol.getName(), symbol.getName(), () -> { + writer.openBlock(CodegenUtils.docFromShape(shape)); writer.openBlock( "return []$L{", "}", diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/IntEnumGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/IntEnumGenerator.java index 55387111bc..93cd412ca3 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/IntEnumGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/IntEnumGenerator.java @@ -60,6 +60,7 @@ public void run() { writer.write("type $L = int32", symbol.getName()).write(""); Set constants = new LinkedHashSet<>(); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer .openBlock( "const (", diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java index ee1b9055a1..bc611a4905 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/StructureGenerator.java @@ -197,6 +197,7 @@ private void renderErrorStructure() { writer.addUseImports(SmithyGoDependency.FMT); ErrorTrait errorTrait = shape.expectTrait(ErrorTrait.class); + writer.openBlock(CodegenUtils.docFromShape(shape)); // Write out a struct to hold the error data. writer .openBlock( @@ -231,6 +232,7 @@ private void renderErrorStructure() { ) .write(""); + writer.openBlock(CodegenUtils.docFromShape(shape)); // write the Error method to satisfy the standard error interface writer.openBlock( "func (e $L) Error() string {", diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/UnionGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/UnionGenerator.java index 38ee96f7ff..347b2ab4b7 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/UnionGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/UnionGenerator.java @@ -59,6 +59,7 @@ public void generateUnion(GoWriter writer) { .forEach(name -> { writer.write("// " + name); }); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer .openBlock( "type $L interface {", @@ -76,6 +77,7 @@ public void generateUnion(GoWriter writer) { String exportedMemberName = symbolProvider.toMemberName(member); Shape target = model.expectShape(member.getTarget()); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer.openBlock( "type $L struct {", "}", @@ -168,6 +170,7 @@ public static void generateUnknownUnion( final Collection unions, final SymbolProvider symbolProvider ) { + // Ignoring API Documentation trait here because this is for Smithy-V2 and we don't use it right now. writer.openBlock( "type $L struct {", "}", diff --git a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/ValidationGenerator.java b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/ValidationGenerator.java index bc9eb6839f..34dcc670dc 100644 --- a/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/ValidationGenerator.java +++ b/codegen/smithy-dafny-codegen/src/main/java/software/amazon/polymorph/smithygo/codegen/ValidationGenerator.java @@ -66,6 +66,7 @@ public void renderValidator( final boolean isInputStructure ) { final Symbol symbol = symbolProvider.toSymbol(shape); + writer.openBlock(CodegenUtils.docFromShape(shape)); writer.openBlock("func (input $L) Validate() (error) {", symbol.getName()); writer.write( renderValidatorHelper(