Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
bjwrk opened this issue Oct 1, 2022 · 4 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@bjwrk
Copy link

bjwrk commented Oct 1, 2022

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
@bjwrk bjwrk changed the title go/doc: Nested list reformatting removes explicitly-written hierarchies in existing comments cmd/gofmt: Nested list reformatting removes explicitly-written hierarchies in existing comments Oct 1, 2022
@mvdan
Copy link
Member

mvdan commented Oct 2, 2022

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

@D1CED
Copy link

D1CED commented Oct 2, 2022

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
Copy link
Member

cc @rsc

@cagedmantis cagedmantis changed the title cmd/gofmt: Nested list reformatting removes explicitly-written hierarchies in existing comments cmd/gofmt: nested list reformatting removes explicitly-written hierarchies in existing comments Oct 6, 2022
@cagedmantis cagedmantis added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Oct 6, 2022
@cagedmantis cagedmantis added this to the Backlog milestone Oct 6, 2022
@cagedmantis
Copy link
Contributor

@griesemer

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

5 participants