go: add more examples to go/* package documentation

[jimmyfrasche]

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:

1. self contained example should be preferred.
2. the example can only parse files in its own package (to avoid unrelated changes breaking them)
3. the files accessed in the example must be included regardless of build tag (so that they're always easily reachable from the "Package files" section in godoc)
4. the example should rely only on features under the Go 1 compatibility agreement (to avoid having to be updated when the package itself is changed)

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.

Based on s/owners, cc: @griesemer @alandonovan @rsc @robpike

[griesemer]

go/constant is mostly intended as a utility package for go/types. But I agree that go/types constant results may require post-processing that could use some examples.

[jimmyfrasche]

I've done such postprocessing before. I'll see if I have anything that can be adapted into examples or at least give me an idea for some good example.

[gopherbot]

Change https://golang.org/cl/100058 mentions this issue: go/token: add example for retrieving Position from Pos

[gopherbot]

Change https://golang.org/cl/100060 mentions this issue: go/parser: add example for using ParseDir with go/build

[gopherbot]

Change https://golang.org/cl/100815 mentions this issue: go/doc: add examples for creating Package and Examples

[gopherbot]

Change https://golang.org/cl/101279 mentions this issue: go/constant: add examples for working with constant.Value

[gopherbot]

Change https://golang.org/cl/101280 mentions this issue: go/importer: add example of importer.For

[gopherbot]

Change https://golang.org/cl/101281 mentions this issue: go/build: add example of build.Import

[jimmyfrasche]

I was looking at the extant examples in go/types.

In addition to #23095, the other two examples use importer.Default which don't work on the playground and won't even with #23603. It looks like they could be changed to use the source importer without any further change. I'll play with those and send a CL if there are no regressions.

I went through the other examples to make sure everything else was running smoothly.

The example in go/printer is not runnable but looks like it will be with once both #23095 and #23603 are resolved.

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.

[gopherbot]

Change https://golang.org/cl/101285 mentions this issue: go/format: move example to external test file

[gopherbot]

Change https://golang.org/cl/101286 mentions this issue: go/types: change examples to use source importer

[gopherbot]

Change https://golang.org/cl/107197 mentions this issue: doc: improve commit messages