Make v3 examples runnable on pkg.go.dev

[matthewdale]

Checklist

• Are you running the latest v3 release? The list of releases is here.
• Did you check the manual for your release? The v3 manual is here.
• Did you perform a search about this feature? Here's the GitHub guide about searching.

What problem does this solve?

The v3 examples are not runnable in the pkg.go.dev documentation. For example, see the Command.Run example.

This is probably caused by a bug in the go/doc example parser, which doesn't handle major version suffixes when resolving package import symbols right now. See golang/go#62059 for more details.

Solution description

Use an import alias in files with testable examples so that the go/doc example parser (used to extract and render examples on pkg.go.dev) can resolve the package import symbols.

E.g.

import cli "github.com/urfave/cli/v3"

Describe alternatives you've considered

The examples not being runnable is probably caused by a bug in the go/doc example AST parser, which doesn't handle major version suffixes when resolving import symbols right now. An alternative is to fix that bug. See golang/go#62059 for that bug report.

[abitrolly]

The examples not being runnable is probably caused by a bug in the go/doc example AST parser, which doesn't handle major version suffixes when resolving import symbols right now.

Is it possible to construct Go playground snippet to validate this bug?

[matthewdale]

@abitrolly Here's an example of trying to extract runnable doc examples from two sample Go test files: https://go.dev/play/p/V8RY15XlJZy

I believe that demonstrates the bug. While it makes sense that doc.Examples can't find a symbol for the cli package when it ends in v3, ending in v3 is a requirement of the Go modules system. Seems like the go/doc package should know how to handle major version suffixes since they're required, hence my suggestion that it's a bug (or at least missing feature) in go/doc.