Open gopherbot opened 11 years ago
The first issue you reported seems a expected output for issue #1835.
There is a tension between gofmt leaving comments alone and "adjusting" them to match surrounding code. There is a know bug where formatting of /* comments is not idempotent (as witnessed in the first example above), and where formatting doesn't change anymore after two applications of gofmt (as is also the case in the first example above). Being completely idempotent is a very hard problem (short of simply running gofmt twice internally). Independent of idempotency, the question is what gofmt should be doing with /* comments. You are suggesting that it should leave it alone if the first line is indented correctly. Perhaps that is the right answer. But I suspect there are counter examples. Leaving alone for now.
Status changed to Thinking.
Another use for leaving /* comments */ completely untouched is for example output with whitespace: https://golang.org/issue/6416
I ran into this issue recently, with an even simpler reproduce case: http://play.golang.org/p/Pwn4cOHtMN
I've done some investigating here.
I ran into this issue recently, with an even simpler reproduce case:
That particular issue is due to an unhandled edge case in stripCommonPrefix
of go/printer
.
It happens when a comment block consists of a first line with /*
, 1 or more blank lines, last line with */
. The internal prefix
variable ends up never being set to a correct value before being used.
Handling it correctly will fix that particular sample I provided (http://play.golang.org/p/Pwn4cOHtMN), but it seems like it's not the same issue as what's described in the original post.
Should I break http://play.golang.org/p/Pwn4cOHtMN out into a separate issue then? Or just consider this current issue to be it?
Okay, I've created failing test cases in https://github.com/shurcooL/play/commit/bfc69a3958c14fb662e71a4fe1ef6906b5f818b0 and a simple fix for the issue in https://github.com/shurcooL/play/commit/f416cec7f1cf85d184e8e0581a17c5c636a36a18. I didn't try to refactor it in any way.
I can submit a CL for review as soon as I'm sure if I should say "fixes #5128" or create a separate issue...
After re-reading the original issue and the responses it received, I feel that I should move http://play.golang.org/p/Pwn4cOHtMN into a separate, much smaller issue. That way I can proceed to make a CL that completely fixes and closes it. So, I've created #9751.
It has a simple and direct fix. I've made a CL for it.
I have an Example test case:
func ExampleDecode() {
call-my-test-case it print some output
// Output:
/*
here is the output in a block comment
in multi lines with different indentation
*/
}
The test case is passing, it's no problem
but when I run go fmt, it constantly change the block comment to this style
/*
here is the output in a block comment
in multi lines with different indentation
*/
and causing test case to FAIL;
wonder is it the same case here, is there any way to let go fmt not touching my block comment?
@c0b There's no way to let go fmt
know that it should leave comments alone. In your case, try the use of //
comments for the Example output instead (e.g., like in https://golang.org/src/text/scanner/example_test.go).
A future gofmt
(version) probably should not touch comments at all, but that has other issues.
It is a real pain to work with multi-line // output:
in example tests. I'm trying to assert YAML
value.
/* ... */
gets broken by gofmt
.//
per-line is unmanageable, I use Goland
to comment multiple lines with hotkey, but it does not add space between //
and line content.Currently I have to paste expected content, add //
with hotkey and then replace //
to //
to make things work.
I would appreciate that gofmt
does not touch comments following // output:
.
There's no way to let go fmt know that it should leave comments alone
how about to change go fmt
to recognize the block comment followed by keywords like Output:
this convention is in-use by go test
; should be considered a builtin feature of go
?
there might be other keywords should be recognized as well, if go fmt
doesn't want to recognize all of them, then may create a special comment marker like gofmt: DO NOT TOUCH
in the first line of the block comment?
A future gofmt (version) probably should not touch comments at all, but that has other issues.
@griesemer are you aware of any ongoing effort of this future gofmt? can connect related PR to here?
I just spent 1 hour trying to get gofmt to leave alone the // output:
of a test example I was working on(https://github.com/golang/go/issues/41980), to no avail; until I searched and came across this issue.
I feel like gofmt re-formatting block comments in the specific case of // output:
of a test example should be a separate issue that should be decided on independent of this one. But maybe this is just my frustration showing.
It seems impossible, at least for me, to get the following reproducer test to pass; if you run gofmt
before running go test
. Because gofmt
will always reformat the // output
comment. And hence this sounds like a bug to me rather than a feature request.
package main
import (
"fmt"
)
func Hello() {
fmt.Printf("Hello \n\nWorld")
}
// 1. https://golang.org/pkg/testing/#hdr-Examples
// 2. https://blog.golang.org/examples
func ExampleHello() {
Hello()
// Output:
// Hello
//
// World
}
This may nor may not be a new example.
Using the GoLand IDE it is possible to recognize and color various types of comment lines, e.g. TODO:
or NOTE:
. Follow-on lines are recognized by an extra space at the beginning (in order to avoid really long lines). For example:
// Note: something something something
// something else
var x int
This example is formatted to:
// Note: something something something
//
// something else
var x int
If the object referenced by the comment (in this case var x int
) is removed the formatting doesn't happen. It does happen in the "middle" of the comment, not just as the last couple of lines.
I realize that this is peculiar to a specific IDE and therefore of the lowest priority. I just thought that I would mention it as this ticket appears to still be open.
@madkins23 What you are seeing there is intentional. See the "Doc Comments" section in the 1.19 release notes (https://go.dev/doc/go1.19).
This issue is specific to block comments written with /* ... */
. Anything involving //
comments is a different issue.
It happens with /* ... */
as well:
/*
Note: something something something
something else
*/
var x int
becomes:
/*
Note: something something something
something else
*/
var x int
I'm aware of the (IMHO) odd ways that comments are processed by godoc
. While I like gofmt
in general I didn't expect it to reinterpret and change my comments. But there it is.
Too bad we can't have markdown in comments. Just saying.
Too bad we can't have markdown in comments. Just saying.
In case you haven't, see the discussion at https://go.googlesource.com/proposal/+/refs/heads/master/design/51082-godocfmt.md#rationale .
Is it possible to just make go fmt completely ignore block comments with eg two **
as in
/**
Leave this alone!
**/
It is quite annoying since I run go fmt as a save hook and recently it started introducing useless reformat changes to copyright blocks particularly ones with indents
//nolint:reformat
Works like a charm.
EDIT:
go1.22.2
by borman@google.com: