gofmt 1.19 reformats comments in a way which breaks go-swagger

[crod...@gmail.com]

Hi,

I have a codebase which uses go-swagger to parse comments in Go files
and generate swagger documentation.

I recently upgraded to Go 1.19, and found that gofmt’s behavior formats
comments in a way which breaks go-swagger.

For example this code:

package somepackage

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"

)

// SomeFunc do something
//
// swagger:operation POST /api/v1/somefunc someFunc
//
// Do something
//
// ---
// x-codeSamples:
// - lang: 'curl'
//   source: |
//       curl -u "${LOGIN}:${PASSWORD}" -d '{"key": "value"}' -X POST   "https://{host}/api/v1/somefunc"
//       curl -u "${LOGIN}:${PASSWORD}" -d '{"key2": "value2"}' -X POST   "https://{host}/api/v1/somefunc"
// responses:
//  '200':
//    description: "Some func"
//    examples:
//      application/json:
//          key: "value"
//  '400':
//    $ref: "#/responses/ErrorResponse"
//  '503':
//    $ref: "#/responses/ErrorResponse"
func SomeFunct(rw http.ResponseWriter, req *http.Request) {
    /// do something
}

Gets reformatted as:

package somepackage

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

// SomeFunc do something
//
// swagger:operation POST /api/v1/somefunc someFunc
//
// # Do something
//
// ---
// x-codeSamples:
//   - lang: 'curl'
//     source: |
//     curl -u "${LOGIN}:${PASSWORD}" -d '{"key": "value"}' -X POST   "https://{host}/api/v1/somefunc"
//     curl -u "${LOGIN}:${PASSWORD}" -d '{"key2": "value2"}' -X POST   "https://{host}/api/v1/somefunc"
//
// responses:
//
//    '200':
//      description: "Some func"
//      examples:
//        application/json:
//            key: "value"
//    '400':
//      $ref: "#/responses/ErrorResponse"
//    '503':
//      $ref: "#/responses/ErrorResponse"
func SomeFunct(rw http.ResponseWriter, req *http.Request) {
    /// do something
}

Specifically the lines under source: |
get re-indented in such a way
that the YAML is invalid, and go-swagger fails to process this file.

This issue has been raised in the go-swagger community:
https://github.com/go-swagger/go-swagger/issues/2759

but I don’t think this can be worked around in go-swagger, since
go-swagger parses the .go files after they have been formatted by gofmt and written to disk.

Can anyone suggest a possible workaround, or a bugfix to gofmt?
Thanks.

—
Craig

​

[K. Alex Mills]

I would hesitate to call this a bug in gofmt. Go released new godoc features as part of Go 1.19, along with reformatting of comments. Those features were entirely intentional.

The decision made in the go-swagger project to place its comments alongside godoc comment blocks was a risky one in case of upstream changes like this one.

That said, maybe a no-reformat directive is in order.

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/d6abf372-4cb1-4070-8a62-d4c6c6ba6bcen%40googlegroups.com.

[Kurtis Rader]

As K. Alex Mills noted gofmt was intentionally enhanced which you can see in the release notes: https://go.dev/blog/go1.19. Specifically, the new support for lists is what's causing you heartburn. See https://go.dev/doc/comment for details. Note this text in that document:

Analysis in 2022 found that only 3% of doc comments in public Go modules were reformatted at all by the draft Go 1.19 gofmt. Limiting ourselves to those comments, about 87% of gofmt’s reformattings preserved the structure that a person would infer from reading the comment; about 6% were tripped up by these kinds of unindented lists, unindented multiline shell commands, and unindented brace-delimited code blocks.

 It seems to me the go-swagger project will need to adapt to the new rules for how Go doc comments are handled by gofmt.

--

You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/d6abf372-4cb1-4070-8a62-d4c6c6ba6bcen%40googlegroups.com.

--

Kurtis Rader

Caretaker of the exceptional canines Junior and Hank

[Ian Lance Taylor]

What are the constraints on go-swagger? Can one simply indent
everything to get a code block?

Ian

> To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/CABx2%3DD9-2%2B6bgb0wjV7V9fJXaCf7KdRssih832Vc5SaCaspxzw%40mail.gmail.com.

[crod...@gmail.com]

I think the parsing rules for go-swagger are described here:

https://goswagger.io/use/spec.html#parsing-rules

It looks like this issue has affected other codebases such as Cockroachdb:

https://github.com/cockroachdb/cockroach/pull/86049#issuecomment-1213573808

—

Craig

[Ivan Porto Carrero]

I think that indenting everything should work, we are detecting the yaml marker, collect all the lines in the comment until we see a thing that starts with swagger: or the comment block ends and then proceed to uncomment and remove the indentation based on the first line after the --- marker.

The branch I'm working in was reformatted by go 1.19 fmt and still passes the tests but I don't think that our test cases capture all the real-world use cases.

[Raphael Ebner]

Hi,
I don't know if this is the right place, but I'm struggling for a few hours now to get my go-swagger document working again and maybe you guys can help me :)

I upgraded from go 1.18 to go 1.19 --> comments for go-swagger are reformatted and go-swagger breaks. So far, so bad. I have read a lot of issues and comments. Now I'm at the point with the latest go 1.19.2 and go-swagger v0.30.3 version. Now the comments are still being reformatted, but I thought with go-swagger v0.30.0 or higher go-swagger can deal with the new comment format and create correct swagger docs?

What am I missing?

Thanks in advance

Raphael