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/doc: "builtin" package is parsed incorrectly without the -u flag #49796

Closed
jroimartin opened this issue Nov 25, 2021 · 1 comment
Closed
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.

Comments

@jroimartin
Copy link
Contributor

jroimartin commented Nov 25, 2021

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

$ go version
go version go1.17.3 linux/amd64

Also tip,

$ go version
go version devel go1.18-45bae64015 Thu Nov 25 04:02:39 2021 +0000 linux/amd64

Does this issue reproduce with the latest release?

Yes, both in stable and tip.

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

go env Output
$ go env
GOOS="linux"
GOARCH="amd64"

What did you do?

Running go doc builtin (without the -u flag).

What did you expect to see?

Every symbol in the "builtin" package should be shown once. Those functions returning a value of type T should be grouped under a type T block. For instance,

type int int
    func cap(v Type) int
    func copy(dst, src []Type) int
    func len(v Type) int

What did you see instead?

go doc shows two entries for the functions cap, copy and len.

go doc builtin Output
$ go doc builtin
package builtin // import "builtin"

Package builtin provides documentation for Go's predeclared identifiers. The
items documented here are not actually in package builtin but their
descriptions here allow godoc to present documentation for the language's
special identifiers.

const true = 0 == 0 ...
const iota = 0
func close(c chan<- Type)
func delete(m map[Type]Type1, key Type)
func panic(v interface{})
func print(args ...Type)
func println(args ...Type)
func recover() interface{}
func cap(v Type) int
func copy(dst, src []Type) int
func len(v Type) int
type ComplexType complex64
    func complex(r, i FloatType) ComplexType
type FloatType float32
    func imag(c ComplexType) FloatType
    func real(c ComplexType) FloatType
type IntegerType int
type Type int
    var nil Type
    func append(slice []Type, elems ...Type) []Type
    func make(t Type, size ...IntegerType) Type
    func new(Type) *Type
type Type1 int
type bool bool
type byte = uint8
type complex128 complex128
type complex64 complex64
type error interface{ ... }
type float32 float32
type float64 float64
type int int
    func cap(v Type) int
    func copy(dst, src []Type) int
    func len(v Type) int
type int16 int16
type int32 int32
type int64 int64
type int8 int8
type rune = int32
type string string
type uint uint
type uint16 uint16
type uint32 uint32
type uint64 uint64
type uint8 uint8
type uintptr uintptr

Bug analysis and proposed fix

cmd/doc forces the -u flag if the package being queried is called "builtin":

		// The builtin package needs special treatment: its symbols are lower
		// case but we want to see them, always.
		if pkg.build.ImportPath == "builtin" {
			unexported = true
		}

The unexported global is used by the function isExported:

// isExported reports whether the name is an exported identifier.
// If the unexported flag (-u) is true, isExported returns true because
// it means that we treat the name as if it is exported.
func isExported(name string) bool {
	return unexported || token.IsExported(name)
}

However, unexported is set to true after calling parsePackage, which calls isExported. So, the package is parsed without taking into account that "builtin" is a special case.

I think this can be fixed moving "if builtin" just after parsing the command arguments and before calling any other function that uses isExported.

I'm sending a CL with the proposed fix and linking it with this issue.

@gopherbot
Copy link

Change https://golang.org/cl/367134 mentions this issue: cmd/doc: fix "builtin" package parsing

@seankhliao seankhliao added the NeedsFix The path to resolution is known, but the work has not been done. label Nov 25, 2021
@golang golang locked and limited conversation to collaborators Nov 26, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants