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

x/pkgsite, x/tools/cmd/godoc: some code examples are not displayed (but work at godoc.org) #40172

Open
vmihailenco opened this issue Jul 12, 2020 · 3 comments

Comments

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jul 13, 2020

Thanks for reporting.

I tested this package at commit go-pg/pg@6fe164e with pkg.go.dev, godoc.org, and x/tools/cmd/godoc, and can confirm the issue is present in pkg.go.dev and x/tools/cmd/godoc, but not godoc.org.

It's also helpful to look at the complete listing of examples at https://godoc.org/github.com/go-pg/pg?tab=doc#pkg-examples, https://pkg.go.dev/github.com/go-pg/pg/v10?tab=doc#pkg-examples, and the output of x/tools/cmd/godoc:

image

This looks like a valid issue. It needs investigation to understand why these examples, which appear to be following the example naming convention correctly, are not showing up in 2 out of 3 documentation viewers. It might be a problem in the example matching logic in go/doc package, or at a higher level. Once we understand why this is happening, it'll be easier to figure out how to fix this.

/cc @julieqiu @shaqque

@dmitshur dmitshur changed the title x/pkgsite: some code examples are not displayed (but work at godoc.org) x/pkgsite, x/tools/cmd/godoc: some code examples are not displayed (but work at godoc.org) Jul 13, 2020
@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jul 13, 2020

One lead to investigate is that the exported DB type is defined as:

type DB struct {
	*baseDB
	ctx context.Context
}

Notably, baseDB is an embedded field. The DB type gets many of its methods indirectly via that embedded baseDB type:

// Begin starts a transaction. Most callers should use RunInTransaction instead.
func (db *baseDB) Begin() (*Tx, error)

The example classification logic in go/doc.NewFromFiles needs to know the complete API to determine if an example should be attached to a given identifier, so if it's not able to handle methods via embedded types, that could be the cause for this.

I haven't confirmed further, just wanted to share this.

@julieqiu julieqiu added the pkgsite label Jul 13, 2020
@shaqque
Copy link
Contributor

@shaqque shaqque commented Jul 13, 2020

@dmitshur you're right that the issue is related to the embedded field. However, this appears to be expected behavior and is documented in https://github.com/golang/go/blob/master/src/go/doc/example.go#L489-L491

if !token.IsExported(m.Name) || m.Level != 0 { // avoid forwarded methods from embedding
	continue
}

Removing

|| m.Level != 0

appears to fix this issue.

The question now is whether we should consider embedded field methods for examples. One problem I can think of is that the embedded field type could also be exported, resulting in duplicate examples. However, we can check for this case easily (i.e. whether the embedded field is exported) and choose not to show the example for either the original struct type or the embedded field type.

/cc @dsnet @griesemer

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.