aws-sdk-go-v2
aws-sdk-go-v2 copied to clipboard
aws
godoc generated docs for service/s3 malformatted
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
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
I appreciate the deep dive but I don't think people outside of Amazon can access that link to the aws-models repo.