cmd/gofmt: nested list reformatting removes explicitly-written hierarchies in existing comments

[bjwrk]

When saving some existing complex comments in some existing Go code that used nested lists inside a preformatted text block, I was quite astonished to find the list was flattened and the hierarchical information thus stripped.

The documentation states that nested lists aren't supported, which is fine, the rationale for the new syntax during the proposal phase made sense to me (at least as far as I was keeping up), but the formatter should leave the nested lists it finds well alone, especially as the author's original intent was already "preformatted block". It's the job of the renderer to fail to render nested lists if they're not supported, not the job of the formatter to strip valuable information on the presumption that the nested list should not have been there in the first place.

For anyone else astonished by this, I have been playing with two specific workarounds (I'm sure there are more):

Prepending > to the start of each line, markdown-quote-style. This fails to render, but rendering is not a problem I actually have, and the intent is very clear, so this is what I'm trying out for now:

> - foo
>   - bar
>     - baz
>   - qux
> - yep

Putting a non-list line at the start of the comment also inhibits the auto-flattening:

  Nobork:
  - foo
    - bar
      - baz
    - qux
  - yep

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

$ go version go1.19 darwin/arm64

Does this issue reproduce with the latest release?

Yes

What did you do?

I saved a file with an existing comment that looked like this (with a few levels deeper)

Here is a hierarchical explanation using nested lists of something complex
that nested lists were a good way to demonstrate:

  - foo
    - bar
      - baz
    - qux
  - yep

What did you see instead?

Here is a hierarchical explanation using nested lists of something complex
that nested lists were a good way to demonstrate:

  - foo
  - bar
  - baz
  - qux
  - yep

[mvdan]

Assuming that this is a godoc comment, how does your hierarchical list render on pkg.go.dev?

[HoffmannJM]

This is already listed in the 'Common mistakes and pitfalls' section of the new Go Doc Comments documentation as the next to last example https://go.dev/doc/comment#mistakes.

[seankhliao]

cc @rsc

[cagedmantis]

@griesemer