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.

Sign up for GitHub

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

Jump to bottom

go/doc/comment: markdown multi-level lists don't work in documentation comments #54894

Closed
Jorropo opened this issue Sep 6, 2022 · 3 comments
Closed

go/doc/comment: markdown multi-level lists don't work in documentation comments #54894

Jorropo opened this issue Sep 6, 2022 · 3 comments
Labels
FrozenDueToAge

Comments

@Jorropo
Copy link
Member

Jorropo commented Sep 6, 2022

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

$ go version
go version go1.19 linux/amd64

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
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/hugo/.cache/go-build"
GOENV="/home/hugo/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/hugo/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/hugo/go"
GOPRIVATE=""
GOPROXY="direct"
GOROOT="/home/hugo/Documents/Scripts/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/hugo/Documents/Scripts/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.19"
GCCGO="gccgo"
GOAMD64="v3"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
GOWORK=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build4005220034=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Load https://go.dev/play/p/au_BiSmy6DK then press format.

What did you expect to see?

// Example
//   - 1
//     - 1.1
package a

// b test stuff
//   - 1
//     - 1.1
type b struct{}

// However this works
//   - 1
//     - 1.1

type farAway struct{}

What did you see instead?

// Example
//   - 1
//   - 1.1
package a

// b test stuff
//   - 1
//   - 1.1
type b struct{}

// However this works
//   - 1
//     - 1.1

type farAway struct{}
@Jorropo Jorropo mentioned this issue Sep 6, 2022
Merged
@seankhliao seankhliao changed the title cmd/go/fmt: markdown multi-level lists don't work if the comment ends directly before a thing go/doc/comment: markdown multi-level lists don't work if the comment ends directly before a thing Sep 6, 2022
@seankhliao
Copy link
Member

This is working as intended: from https://pkg.go.dev/go/doc/comment#pkg-overview , doc comments are only:

Package comment implements parsing and reformatting of Go doc comments, (documentation comments), which are comments that immediately precede a top-level declaration of a package, const, func, type, or var.

@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Sep 6, 2022
@Jorropo Jorropo changed the title go/doc/comment: markdown multi-level lists don't work if the comment ends directly before a thing go/doc/comment: markdown multi-level lists don't work in documentation comments Sep 6, 2022
@Jorropo
Copy link
Member Author

Jorropo commented Sep 6, 2022

@seankhliao thx I didn't knew how this was called, however this isn't solving my issue.
Now I find that the Go Doc Comments spec doesn't support nested lists.

If I want to add support for that, how can I do this ? Should I open a proposal ?

@seankhliao
Copy link
Member

This is an explicit design choice: link to design doc

Note also that there are no code blocks inside list items—any indented paragraph following a list item continues the list item, and the list ends at the next unindented line—nor are there nested lists. This avoids any the space-counting subtlety like in Markdown.

@golang golang locked and limited conversation to collaborators Sep 6, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@gopherbot @seankhliao @Jorropo