codegen: Update API client to include package docs

codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/CodegenUtils.java

@@ -31,12 +31,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 +399,16 @@ public static MemberShape expectMember(StructureShape shape, Predicate<String> 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) {
+        return shape.getTrait(TitleTrait.class).map(TitleTrait::getValue).orElse(fallback);
+    }
 }

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();

codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoWriter.java

@@ -56,13 +56,20 @@ public final class GoWriter extends CodeWriter {
 
     private int docWrapLength = DEFAULT_DOC_WRAP_LENGTH;
 
+    private CodeWriter packageDocs;
+
     public GoWriter(String fullPackageName) {
         this.fullPackageName = fullPackageName;
         trimBlankLines();
         trimTrailingSpaces();
         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<SymbolDependency> 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 void writeDocs(CodeWriter writer, Runnable runnable) {
+        writer.pushState("docs");
+        writer.setNewlinePrefix("// ");
         runnable.run();
-        setNewlinePrefix("");
-        popState();
-        return this;
+        writer.setNewlinePrefix("");
+        writer.popState();
+    }
+
+    private 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;
     }
 
     /**

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);
         });