Skip to content

Commit

Permalink
private/model/api: Improve SDK API reference doc generation (#2617)
Browse files Browse the repository at this point in the history 
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 #2572
Fix #2374
  • Loading branch information
@jasdel
jasdel authored May 24, 2019
1 parent 486b921 commit afbf73b
Showing 187 changed files with 7,155 additions and 8,194 deletions.
590 changes: 359 additions & 231 deletions private/model/api/docstring.go
View file

Large diffs are not rendered by default.

159 changes: 70 additions & 89 deletions private/model/api/docstring_test.go
View file
Original file line number Diff line number Diff line change
@@ -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)
}
})
}
}
4 changes: 2 additions & 2 deletions private/model/api/example.go
View file
Original file line number Diff line number Diff line change
@@ -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 . }}
2 changes: 1 addition & 1 deletion private/model/api/operation.go
View file
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions service/acm/api.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

49 changes: 21 additions & 28 deletions service/acmpca/api.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit afbf73b

Please sign in to comment.