From 03fdcc307fb8610f7c880caf2a1f5c66ca3f7185 Mon Sep 17 00:00:00 2001 From: Jason Del Ponte Date: Wed, 14 Oct 2020 11:33:42 -0700 Subject: [PATCH 1/2] codegen: Update API client to include package docs Adds generation of Go package does for API client packages. This takes the API client service model's "description" and uses it as the package doc for the API client package. --- .../smithy/go/codegen/CodegenUtils.java | 20 ++++++ .../smithy/go/codegen/CodegenVisitor.java | 11 ++++ .../amazon/smithy/go/codegen/GoWriter.java | 61 +++++++++++++++---- .../smithy/go/codegen/ServiceGenerator.java | 4 +- 4 files changed, 83 insertions(+), 13 deletions(-) diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java index 2217a2480..d677b8211 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java @@ -23,6 +23,7 @@ import java.util.ArrayList; import java.util.Comparator; import java.util.List; +import java.util.Optional; import java.util.function.Predicate; import java.util.logging.Logger; import software.amazon.smithy.codegen.core.CodegenException; @@ -31,12 +32,14 @@ import software.amazon.smithy.model.Model; import software.amazon.smithy.model.shapes.CollectionShape; import software.amazon.smithy.model.shapes.MemberShape; +import software.amazon.smithy.model.shapes.ServiceShape; import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.ShapeId; import software.amazon.smithy.model.shapes.ShapeType; import software.amazon.smithy.model.shapes.StructureShape; import software.amazon.smithy.model.traits.EnumTrait; import software.amazon.smithy.model.traits.RequiredTrait; +import software.amazon.smithy.model.traits.TitleTrait; import software.amazon.smithy.utils.StringUtils; /** @@ -397,4 +400,21 @@ public static MemberShape expectMember(StructureShape shape, Predicate m .findFirst() .orElseThrow(() -> new CodegenException("did not find member in structure shape, " + shape.getId())); } + + /** + * Attempts to get the title of the API's service from the model. If unalbe to get the title the fallback value + * will be returned instead. + * + * @param shape service shape + * @param fallback string to return if service does not have a title + * @return title of service + */ + public static String getServiceTitle(ServiceShape shape, String fallback) { + Optional titleTrait = shape.getTrait(TitleTrait.class); + if (titleTrait.isPresent()) { + return titleTrait.get().getValue(); + } + + return fallback; + } } diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenVisitor.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenVisitor.java index 1ae861e5b..f1957e724 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenVisitor.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenVisitor.java @@ -262,6 +262,17 @@ public Void serviceShape(ServiceShape shape) { return null; } + // Write API client's package doc for the service. + writers.useFileWriter("doc.go", settings.getModuleName(), (writer) -> { + writer.writePackageDocs(String.format( + "Package %s provides the API client, operations, and parameter types for %s.", + CodegenUtils.getDefaultPackageImportName(settings.getModuleName()), + CodegenUtils.getServiceTitle(shape, "the API"))); + writer.writePackageDocs(""); + writer.writePackageShapeDocs(shape); + }); + + // Write API client type and utilities. writers.useShapeWriter(shape, serviceWriter -> { new ServiceGenerator(settings, model, symbolProvider, serviceWriter, shape, integrations, runtimePlugins, applicationProtocol).run(); diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java index 609a52bf1..cd779289e 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java @@ -56,6 +56,8 @@ public final class GoWriter extends CodeWriter { private int docWrapLength = DEFAULT_DOC_WRAP_LENGTH; + private CodeWriter packageDocs; + public GoWriter(String fullPackageName) { this.fullPackageName = fullPackageName; trimBlankLines(); @@ -63,6 +65,11 @@ public GoWriter(String fullPackageName) { setIndentText("\t"); putFormatter('T', new GoSymbolFormatter()); putFormatter('P', new PointableGoSymbolFormatter()); + + packageDocs = new CodeWriter(); + packageDocs.trimBlankLines(); + packageDocs.trimTrailingSpaces(); + packageDocs.setIndentText("\t"); } /** @@ -208,13 +215,17 @@ Collection getDependencies() { * @param runnable Runnable that handles actually writing docs with the writer. * @return Returns the writer. */ - private GoWriter writeDocs(Runnable runnable) { - pushState("docs"); - setNewlinePrefix("// "); + private static void writeDocs(CodeWriter writer, Runnable runnable) { + writer.pushState("docs"); + writer.setNewlinePrefix("// "); runnable.run(); - setNewlinePrefix(""); - popState(); - return this; + writer.setNewlinePrefix(""); + writer.popState(); + } + + private static void writeDocs(CodeWriter writer, int docWrapLength, String docs) { + String wrappedDoc = StringUtils.wrap(DocumentationConverter.convert(docs), docWrapLength); + writeDocs(writer, () -> writer.write(wrappedDoc.replace("$", "$$"))); } /** @@ -226,8 +237,18 @@ private GoWriter writeDocs(Runnable runnable) { * @return Returns the writer. */ public GoWriter writeDocs(String docs) { - String wrappedDoc = StringUtils.wrap(DocumentationConverter.convert(docs), docWrapLength); - writeDocs(() -> write(wrappedDoc.replace("$", "$$"))); + writeDocs(this, docWrapLength, docs); + return this; + } + + /** + * Writes the doc to the Go package docs that are written prior to the go package statement. + * + * @param docs documentation to write to package doc. + * @return writer + */ + public GoWriter writePackageDocs(String docs) { + writeDocs(packageDocs, docWrapLength, docs); return this; } @@ -246,6 +267,21 @@ boolean writeShapeDocs(Shape shape) { }).orElse(false); } + /** + * Writes shape documentation comments to the writer's package doc if docs are present. + * + * @param shape Shape to write the documentation of. + * @return Returns true if docs were written. + */ + boolean writePackageShapeDocs(Shape shape) { + return shape.getTrait(DocumentationTrait.class) + .map(DocumentationTrait::getValue) + .map(docs -> { + writePackageDocs(docs); + return true; + }).orElse(false); + } + /** * Writes member shape documentation comments if docs are present. * @@ -278,9 +314,10 @@ boolean writeMemberDocs(Model model, MemberShape member) { public String toString() { String contents = super.toString(); String[] packageParts = fullPackageName.split("/"); - String header = String.format( - "// Code generated by smithy-go-codegen DO NOT EDIT.%n%npackage %s%n%n", - packageParts[packageParts.length - 1]); + String header = String.format("// Code generated by smithy-go-codegen DO NOT EDIT.%n%n"); + + String packageDocs = this.packageDocs.toString(); + String packageStatement = String.format("package %s%n%n", packageParts[packageParts.length - 1]); String importString = imports.toString(); String strippedContents = StringUtils.stripStart(contents, null); @@ -291,7 +328,7 @@ public String toString() { return header + strippedImportString + "\n" + strippedContents; } - return header + importString + contents; + return header + packageDocs + packageStatement + importString + contents; } /** diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/ServiceGenerator.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/ServiceGenerator.java index 24f1a831e..904f53bef 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/ServiceGenerator.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/ServiceGenerator.java @@ -75,7 +75,9 @@ public void run() { writer.write(""); Symbol serviceSymbol = symbolProvider.toSymbol(service); - writer.writeShapeDocs(service); + writer.writeDocs(String.format("%s provides the API client to make operations call for %s.", + serviceSymbol.getName(), + CodegenUtils.getServiceTitle(service, "the API"))); writer.openBlock("type $T struct {", "}", serviceSymbol, () -> { writer.write("options $L", CONFIG_NAME); }); From 340a3e86ce7c3a8b3dfa10ca8ab8e51320af7b63 Mon Sep 17 00:00:00 2001 From: Jason Del Ponte Date: Wed, 14 Oct 2020 15:15:16 -0700 Subject: [PATCH 2/2] pr feedback fixup --- .../software/amazon/smithy/go/codegen/CodegenUtils.java | 8 +------- .../java/software/amazon/smithy/go/codegen/GoWriter.java | 4 ++-- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java index d677b8211..4e39a61bf 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java @@ -23,7 +23,6 @@ import java.util.ArrayList; import java.util.Comparator; import java.util.List; -import java.util.Optional; import java.util.function.Predicate; import java.util.logging.Logger; import software.amazon.smithy.codegen.core.CodegenException; @@ -410,11 +409,6 @@ public static MemberShape expectMember(StructureShape shape, Predicate m * @return title of service */ public static String getServiceTitle(ServiceShape shape, String fallback) { - Optional titleTrait = shape.getTrait(TitleTrait.class); - if (titleTrait.isPresent()) { - return titleTrait.get().getValue(); - } - - return fallback; + return shape.getTrait(TitleTrait.class).map(TitleTrait::getValue).orElse(fallback); } } diff --git a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java index cd779289e..8c448b3e1 100644 --- a/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java +++ b/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java @@ -215,7 +215,7 @@ Collection getDependencies() { * @param runnable Runnable that handles actually writing docs with the writer. * @return Returns the writer. */ - private static void writeDocs(CodeWriter writer, Runnable runnable) { + private void writeDocs(CodeWriter writer, Runnable runnable) { writer.pushState("docs"); writer.setNewlinePrefix("// "); runnable.run(); @@ -223,7 +223,7 @@ private static void writeDocs(CodeWriter writer, Runnable runnable) { writer.popState(); } - private static void writeDocs(CodeWriter writer, int docWrapLength, String docs) { + private void writeDocs(CodeWriter writer, int docWrapLength, String docs) { String wrappedDoc = StringUtils.wrap(DocumentationConverter.convert(docs), docWrapLength); writeDocs(writer, () -> writer.write(wrappedDoc.replace("$", "$$"))); }