x/pkgsite: package example skips critical package import

[AndrewGMorgan]

What is the URL of the page with the issue?

https://pkg.go.dev/kernel.org/pub/linux/libs/security/libcap/cap@v1.2.73#example-Set.Fill

What is your user agent?

Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36

Screenshot

What did you do?

I've been trying to include some package examples and this latest attempt is almost there...

The source for this file is: https://git.kernel.org/pub/scm/libs/libcap/libcap.git/tree/cap/cap_examples_test.go?id=6ef6a9d1e415c0b75e5acbcbcbfbda86d4ba6b91#n9

Which includes the header for the needed package. However, that package is omitted when the example renders.

What did you see happen?

The example is as hoped for minus the all important:

"kernel.org/pub/linux/libs/security/libcap/cap"

package reference.

What did you expect to see?

As provided in the example source, I expected this package to be listed in the example. If I manually put it there in the documented example on the website, and run that example, it generates the expected result.

[gabyhelp]

Related Issues

• x/pkgsite: Package-level example not showing up on pkg.go.dev #48705 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

Duplicate of #70611

[ianlancetaylor]

Is this really a dup? This seems to say that something is hiding the import in the example, which sounds like a bug.

[seankhliao]

My read of both issues is the same: go/doc synthesizes a main package from an example defined in a foo_test package. In resolving identifiers (to decide if it needs to include an import), it skips anything that is predeclared.

the synthesis func: https://go.googlesource.com/go/+/caee788a48f19814bd778c1bd2422cb6f60ad810/src/go/doc/example.go#197
previous analysis #70611 (comment)

[AndrewGMorgan]

My worry is that this is not doing as consistent a job of parsing vs whatever the back-end does to safely run the code. I can hand edit the example in the documentation web page, by adding in the missing package import, and the example then runs just fine. I'm thinking of editing the example code body to point to this bug, via a comment, and explain that that is what the reader will have to do to make the example run on pkg.go.dev.

[ianlancetaylor]

Oh, I get it now, the problem is that the package is named cap, and cap is also a predeclared identifier. You're right, this is a dup. And we should fix the bug: the package import should not be removed, and should shadow the predeclared identifier. Thanks.

[gopherbot]

Change https://go.dev/cl/639175 mentions this issue: go/doc: resolve imports before predeclared identifiers in examples

[AndrewGMorgan]

Despite the status of "Not planned", this bug was actually fixed and I've just seen that it is now deployed. The libcap cap/v1.2.76 release will no longer include workarounds in the examples.