golang/go

go: add more examples to go/* package documentation

Open

#24,352 opened on Mar 11, 2018

View on GitHub
 (12 comments) (0 reactions) (0 assignees)Go (19,008 forks)batch import
DocumentationNeedsInvestigationhelp wanted

Repository metrics

Stars
 (133,883 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

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

Contributor guide