godoc generated docs for service/s3 malformatted

[bartgrantham]

Describe the issue

The comments for service/s3 are formatted in a way that confuses godoc and results in slightly garbled documentation.

For example, see the codeblock that's created from the indents in service/s3/api_op_GetObject.go: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.GetObject (search for "depends on whether you also have the s3:ListBucket permission")

Links

https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.GetObject

AWS Go SDK V2 Module Versions Used

github.com/aws/aws-sdk-go-v2/service/s3 v1.71.0

[Madrigal]

For context, the SDK team receives the documentation directly from the service team, and then we do some light transformations on top of it.

What you're describing seems to be happening because of what's described on go doc common mistakes

The rule that any span of indented or blank lines in a doc comment is rendered as a code block dates to the earliest days of Go. Unfortunately, the lack of support for doc comments in gofmt has led to many existing comments that use indentation without meaning to create a code block.

The raw docs for this section (which you can findhere) looks like this

<p>If the object you request doesn't exist, the error that Amazon S3 returns\n                        depends on whether you also have the <code>s3:ListBucket</code>\n                        permission.</p>\n                     <ul>

so it's likely that that extra space gets converted into a code block.

An idea would be to identify any blank space that is not inside any HTML tag and remove it since it's not semantically relevant, and that way we wouldn't have this issue. This would imply making changes in Smithy Go on our Doc converter

[bartgrantham]

I appreciate the deep dive but I don't think people outside of Amazon can access that link to the aws-models repo.

[Madrigal]

My bad, most SDKs (Go included) have a similar aws-models. Ours is included here (updated the original one to point here)

Note that this is for reference only, since SDKs don't own this data and we can't make decisions as to what is or is not included here