Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
x/pkgsite, x/tools/cmd/godoc: some code examples are not displayed (but work at godoc.org) #40172
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:
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
One lead to investigate is that the exported
The example classification logic in
I haven't confirmed further, just wanted to share this.
@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
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.