cmd/gofmt: indenting removed from multi-line bullet-lists inside numbered lists

[thaJeztah]

What version of Go are you using (go version)?

$ go version
go version go1.19.2 darwin/arm64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env

(probably not relevant)

What did you do?

Given the following file;

/*
Package main is an example.

 1. Item 1.
 2. Item 2.
    - SubItem 1.
    - SubItem 2.
    - SubItem 3 spans two lines. Lorem ipsum dolor sit amet, consectetur
      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
    - Subitem 3 spans three lines. Lorem ipsum dolor sit amet, consectetur
      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
      Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
*/
package main

Running gofmt reformat the bullet-list, removing the indentation for bullets spanning multiple lines;

gofmt -d .
diff main.go.orig main.go
--- main.go.orig
+++ main.go
@@ -6,9 +6,9 @@
     - SubItem 1.
     - SubItem 2.
     - SubItem 3 spans two lines. Lorem ipsum dolor sit amet, consectetur
-      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
+    adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
     - Subitem 3 spans three lines. Lorem ipsum dolor sit amet, consectetur
-      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
-      Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
+    adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
+    Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
 */
 package main

I also tried adding whitespace after the bullet-list (following the example at https://go.dev/doc/comment#mistakes):

/*
Package main is an example.

 1. Item 1.

 2. Item 2.

    - SubItem 1.
    - SubItem 2.
    - SubItem 3 spans two lines. Lorem ipsum dolor sit amet, consectetur
      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
    - Subitem 3 spans three lines. Lorem ipsum dolor sit amet, consectetur
      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
      Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
*/
package main

But this gave the same result;

gofmt -d .
diff main.go.orig main.go
--- main.go.orig
+++ main.go
@@ -8,10 +8,9 @@
     - SubItem 1.
     - SubItem 2.
     - SubItem 3 spans two lines. Lorem ipsum dolor sit amet, consectetur
-      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
+    adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
     - Subitem 3 spans three lines. Lorem ipsum dolor sit amet, consectetur
-      adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
-      Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
+    adipiscing elit. Morbi porta eros nunc, in viverra ex porttitor vitae.
+    Mauris nisi magna, faucibus quis velit vitae, euismod convallis magna.
 */
 package main

What did you expect to see?

The indentation preserved.

What did you see instead?

The indentation removed.

[mvdan]

I'm fairly sure that this is a duplicate of https://github.com/golang/go/issues/55990. Even if the case is not exactly the same, the two issues seem to be about gofmt and the indentation of bulleted lists, so I think using a single issue will be less confusing.

[thaJeztah]

I saw that one, but that one looks like it's trying nested bullet-lists, which are documented as not supported;

Go doc comments do not support nested lists, so gofmt reformats

So the alternative suggested there is to use a numbered list, and embed the bullet list in it.

That said, it could definitely have the same cause. The "interesting" bit is that it does format the first lines of the bullet list correctly, so I wonder if the bug is cause by the formatter taking the indentation level of the outer list, and applying it to those "second" lines.

I must admit that I haven't looked at the formatting code at all though 😅

[mvdan]

You're right, that issue was about nested lists, I forgot that.

[cagedmantis]

@griesemer

[gopherbot]

Change https://go.dev/cl/446775 mentions this issue: go/doc/comment: correct indent format of nested list on Doc comments

[HeCorr]

Hello, I've recently updated Go from 1.18 to 1.20 and noticed most multi-line comments have lost their original formatting:

It was previously spaced like that to be more readable:

in comparison to:

What is the reason for the change? And could it be reverted to allow such formatting again? Thanks!

[ianlancetaylor]

@HeCorr Please paste plain text as plain text, not images. Images are much harder to read. Thanks.

The change you are describing is documented at https://go.dev/doc/go1.19#go-doc. The links there explain how you can get doc comments that format correctly in both text and HTML.

[ianlancetaylor]

I'm closing this issue because the comment is working according to the current doc comment formatting rules.