Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
go: add more examples to go/* package documentation #24352
It can be hard to figure out how to use the go/* packages. More examples will help.
Coming up with useful, short examples that demonstrate these packages well will be hard and ongoing and probably require some discussion, hence this meta-issue.
A complimentary wiki page (what would a good name for this page be?), in the vein of https://github.com/golang/go/wiki/cgo , would be helpful for larger or more complicated examples, some notes about when to use which package, links to helpful packages in golang.org/x/tools/go, and for various tips and tricks, but having playable examples of the basics will be very helpful.
Related issue: #23603 so that examples can rely on go/parser and go/build can still be playable even if they hit the fs. I think this should be okay with the following rules:
Here are some potential examples to include:
An example in go/parser that uses go/build and ParseDir to get the *ast.Package given an import path. (This seems to be a common stumbling block, in my experience).
Some examples in go/constant using BinaryOp and Compare and some of the conversions/constructors.
An example in go/token of using the FileSet to turn a Pos into a Position.
I was looking at the extant examples in go/types.
In addition to #23095, the other two examples use
I went through the other examples to make sure everything else was running smoothly.
The example in go/format is not runnable. It is not clear to me why it is not. However, it also should be in an external test file per #11257 and putting it in one makes it runnable, so I'll send a CL.