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

go/doc: Some functions with type parameters omitted #49477

Closed
muhlemmer opened this issue Nov 9, 2021 · 4 comments
Closed

go/doc: Some functions with type parameters omitted #49477

muhlemmer opened this issue Nov 9, 2021 · 4 comments
Labels
FrozenDueToAge release-blocker Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@muhlemmer
Copy link
Contributor

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

$ go version
go version devel go1.18-b7529c3 Tue Nov 9 06:27:04 2021 +0000 linux/amd64

Does this issue reproduce with the latest release?

N/A

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

Custom VSCode devcontainer, Dockerfile based on golang:latest, but running a Go build of the latest master branch.

go env Output
$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/vscode/.cache/go-build"
GOENV="/home/vscode/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/master/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/master/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="devel go1.18-b7529c3 Tue Nov 9 06:27:04 2021 +0000"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/workspace/go.mod"
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 -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3516386950=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Some functions that take type parameters, are ignored / not documented by godoc http server. Notably I found generic functions that return a value or slice of Type are omitted in the documentation output. While functions which receive an argument of a generic Type are represented in the documentation.

I've created a small Github repo to easily reproduce. It contains a source.go file with generic functions, and a Dockerfile that build the latest golang/go:master with x/tools/cmd/godoc@master:

  1. git clone https://github.com/muhlemmer/godoc_generics_issue.git
  2. docker build -t ggi .
  3. docker run -p 6060:6060 ggi
  4. Browse to http://localhost:6060/pkg/github.com/muhlemmer/godoc_generics_issue/

What did you expect to see?

All exported functions, with or without type parameters to be documented.

What did you see instead?

This function is documented:

func Print[T proto.Message](s []T) {
	for _, v := range s {
		fmt.Println(v)
	}
}

This functions are missing:

func Slice[T any]() []T {
	return nil
}

func Single[T any]() *T {
	return nil
}
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Nov 9, 2021
@gopherbot gopherbot added this to the Unreleased milestone Nov 9, 2021
@findleyr
Copy link
Contributor

findleyr commented Nov 9, 2021

CC @jba @ianthehat

I will look into this to make sure it's not a bug with the standard library go/doc package, but x/tools/cmd/godoc itself is a relatively lower priority to update for generics than pkgsite (#48264), which also has a command to run locally. With that said, it may be the case that this is an easy fix.

Assigning to myself for investigation.

@findleyr findleyr self-assigned this Nov 9, 2021
@muhlemmer
Copy link
Contributor Author

When I run the go doc -all command, the output has the same functions missing in output:

package godoc_generics_issue // import "github.com/muhlemmer/godoc_generics_issue"


FUNCTIONS

func Print[T any](s []T)
    Print prints the elements of a slice. It should be possible to call this
    with any slice value.

So this might indeed be a go/doc library issue. Hope this helps your investigation.

@findleyr findleyr changed the title x/tools/cmd/godoc: Some functions with type parameters ommited go/doc: Some functions with type parameters omitted Nov 10, 2021
@findleyr findleyr modified the milestones: Unreleased, Go1.18 Nov 10, 2021
@findleyr
Copy link
Contributor

@muhlemmer really appreciate your dilligence here.

It is indeed a go/doc issue: these functions are being interpreted as 'constructors' of the type parameter T (because from syntax alone, T looks like a defined type).

Fortunately we can work around this without type checking. Fix incoming.

@gopherbot
Copy link

Change https://golang.org/cl/362758 mentions this issue: go/doc: don't treat functions returning type parameters as constructors

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge release-blocker Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

3 participants