private/model/api: Improve SDK API reference doc generation (aws#2617)

Improves the SDK's generated documentation for API client, operation, and types. This fixes several bugs in the doc generation causing poor formatting, an difficult to read reference documentation.

Fix aws#2572
Fix aws#2374

private/model/api/docstring_test.go

@@ -1,100 +1,81 @@
-// +build 1.6,codegen
+// +build go1.8,codegen
 
 package api
 
 import (
 	"testing"
 )
 
-func TestNonHTMLDocGen(t *testing.T) {
-	doc := "Testing 1 2 3"
-	expected := "// Testing 1 2 3\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-}
-
-func TestListsHTMLDocGen(t *testing.T) {
-	doc := "<ul><li>Testing 1 2 3</li> <li>FooBar</li></ul>"
-	expected := "//    * Testing 1 2 3\n//    * FooBar\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-
-	doc = "<ul> <li>Testing 1 2 3</li> <li>FooBar</li> </ul>"
-	expected = "//    * Testing 1 2 3\n//    * FooBar\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-
-	// Test leading spaces
-	doc = " <ul> <li>Testing 1 2 3</li> <li>FooBar</li> </ul>"
-	doc = docstring(doc)
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-
-	// Paragraph check
-	doc = "<ul> <li> <p>Testing 1 2 3</p> </li><li> <p>FooBar</p></li></ul>"
-	expected = "//    * Testing 1 2 3\n// \n//    * FooBar\n"
-	doc = docstring(doc)
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-}
-
-func TestInlineCodeHTMLDocGen(t *testing.T) {
-	doc := "<ul> <li><code>Testing</code>: 1 2 3</li> <li>FooBar</li> </ul>"
-	expected := "//    * Testing: 1 2 3\n//    * FooBar\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-}
-
-func TestInlineCodeInParagraphHTMLDocGen(t *testing.T) {
-	doc := "<p><code>Testing</code>: 1 2 3</p>"
-	expected := "// Testing: 1 2 3\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
+func TestDocstring(t *testing.T) {
+	cases := map[string]struct {
+		In     string
+		Expect string
+	}{
+		"non HTML": {
+			In:     "Testing 1 2 3",
+			Expect: "// Testing 1 2 3",
+		},
+		"link": {
+			In:     `<a href="https://example.com">a link</a>`,
+			Expect: "// a link (https://example.com)",
+		},
+		"link with space": {
+			In:     `<a href=" https://example.com">a link</a>`,
+			Expect: "// a link (https://example.com)",
+		},
+		"list HTML 01": {
+			In:     "<ul><li>Testing 1 2 3</li> <li>FooBar</li></ul>",
+			Expect: "//    * Testing 1 2 3\n// \n//    * FooBar",
+		},
+		"list HTML 02": {
+			In:     "<ul> <li>Testing 1 2 3</li> <li>FooBar</li> </ul>",
+			Expect: "//    * Testing 1 2 3\n// \n//    * FooBar",
+		},
+		"list HTML leading spaces": {
+			In:     " <ul> <li>Testing 1 2 3</li> <li>FooBar</li> </ul>",
+			Expect: "//    * Testing 1 2 3\n// \n//    * FooBar",
+		},
+		"list HTML paragraph": {
+			In:     "<ul> <li> <p>Testing 1 2 3</p> </li><li> <p>FooBar</p></li></ul>",
+			Expect: "//    * Testing 1 2 3\n// \n//    * FooBar",
+		},
+		"inline code HTML": {
+			In:     "<ul> <li><code>Testing</code>: 1 2 3</li> <li>FooBar</li> </ul>",
+			Expect: "//    * Testing: 1 2 3\n// \n//    * FooBar",
+		},
+		"complex list paragraph": {
+			In:     "<ul> <li><p><code>FOO</code> Bar</p></li><li><p><code>Xyz</code> ABC</p></li></ul>",
+			Expect: "//    * FOO Bar\n// \n//    * Xyz ABC",
+		},
+		"inline code in paragraph": {
+			In:     "<p><code>Testing</code>: 1 2 3</p>",
+			Expect: "// Testing: 1 2 3",
+		},
+		"root pre": {
+			In:     "<pre><code>Testing</code></pre>",
+			Expect: "//    Testing",
+		},
+		"paragraph": {
+			In:     "<p>Testing 1 2 3</p>",
+			Expect: "// Testing 1 2 3",
+		},
+		"wrap lines": {
+			In:     "<span data-target-type=\"operation\" data-service=\"secretsmanager\" data-target=\"CreateSecret\">CreateSecret</span> <span data-target-type=\"structure\" data-service=\"secretsmanager\" data-target=\"SecretListEntry\">SecretListEntry</span> <span data-target-type=\"structure\" data-service=\"secretsmanager\" data-target=\"CreateSecret$SecretName\">SecretName</span> <span data-target-type=\"structure\" data-service=\"secretsmanager\" data-target=\"SecretListEntry$KmsKeyId\">KmsKeyId</span>",
+			Expect: "// CreateSecret SecretListEntry SecretName KmsKeyId",
+		},
+		"links with spaces": {
+			In:     "<p> Deletes the replication configuration from the bucket. For information about replication configuration, see <a href=\" https://docs.aws.amazon.com/AmazonS3/latest/dev/crr.html\">Cross-Region Replication (CRR)</a> in the <i>Amazon S3 Developer Guide</i>. </p>",
+			Expect: "// Deletes the replication configuration from the bucket. For information about\n// replication configuration, see Cross-Region Replication (CRR) (https://docs.aws.amazon.com/AmazonS3/latest/dev/crr.html)\n// in the Amazon S3 Developer Guide.",
+		},
 	}
-}
-
-func TestEmptyPREInlineCodeHTMLDocGen(t *testing.T) {
-	doc := "<pre><code>Testing</code></pre>"
-	expected := "//    Testing\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-}
-
-func TestParagraph(t *testing.T) {
-	doc := "<p>Testing 1 2 3</p>"
-	expected := "// Testing 1 2 3\n"
-	doc = docstring(doc)
-
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
-	}
-}
-
-func TestComplexListParagraphCode(t *testing.T) {
-	doc := "<ul> <li><p><code>FOO</code> Bar</p></li><li><p><code>Xyz</code> ABC</p></li></ul>"
-	expected := "//    * FOO Bar\n// \n//    * Xyz ABC\n"
-	doc = docstring(doc)
 
-	if expected != doc {
-		t.Errorf("Expected %s, but received %s", expected, doc)
+	for name, c := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Log("Input", c.In)
+			actual := docstring(c.In)
+			if e, a := c.Expect, actual; e != a {
+				t.Errorf("expect %q, got %q", e, a)
+			}
+		})
 	}
 }

private/model/api/example.go

@@ -54,9 +54,9 @@ var exampleCustomizations = map[string]template.FuncMap{}
 
 var exampleTmpls = template.Must(template.New("example").Funcs(exampleFuncMap).Parse(`
 {{ generateTypes . }}
-{{ commentify (wrap .Title 80 false) }}
+{{ commentify (wrap .Title 80) }}
 //
-{{ commentify (wrap .Description 80 false) }}
+{{ commentify (wrap .Description 80) }}
 func Example{{ .API.StructName }}_{{ .MethodName }}() {
 	svc := {{ .API.PackageName }}.New(session.New())
 	input := {{ generateExampleInput . }}

private/model/api/operation.go

@@ -307,7 +307,7 @@ func (c *{{ .API.StructName }}) {{ .ExportedName }}WithContext(` +
 //    // Example iterating over at most 3 pages of a {{ .ExportedName }} operation.
 //    pageNum := 0
 //    err := client.{{ .ExportedName }}Pages(params,
-//        func(page {{ .OutputRef.GoType }}, lastPage bool) bool {
+//        func(page {{ .OutputRef.Shape.GoTypeWithPkgName }}, lastPage bool) bool {
 //            pageNum++
 //            fmt.Println(page)
 //            return pageNum <= 3