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 #40172

vmihailenco opened this issue Jul 12, 2020 · 3 comments


Copy link

@dmitshur dmitshur commented Jul 13, 2020

Thanks for reporting.

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

It's also helpful to look at the complete listing of examples at,, and the output of x/tools/cmd/godoc:


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 x/pkgsite, x/tools/cmd/godoc: some code examples are not displayed (but work at Jul 13, 2020
Copy link

@dmitshur dmitshur commented Jul 13, 2020

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

type DB struct {
	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
Copy link

@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

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


|| 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
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.