Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

go: add more examples to go/* package documentation #24352

Open
jimmyfrasche opened this issue Mar 11, 2018 · 12 comments
Open

go: add more examples to go/* package documentation #24352

jimmyfrasche opened this issue Mar 11, 2018 · 12 comments
Labels
Documentation help wanted
Milestone
Unplanned

Comments

@jimmyfrasche
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member Author

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
Copy link

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

@andybons andybons changed the title Add more examples to go/* packages go: add more examples to go/* package documentation Mar 12, 2018
@andybons andybons added this to the Unplanned milestone Mar 12, 2018
@gopherbot
Copy link

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

gopherbot pushed a commit that referenced this issue Mar 13, 2018
@jimmyfrasche @griesemer
go/token: add example for retrieving Position from Pos
867d07f 
There are few uses for the majority of the API in go/token for the
average user. The exception to this is getting the filename, line, and
column information from a token.Pos (reported and absolute. This is
straightforward but figuring out how to do it requires combing through
a lot of documentation. This example makes it more easily discoverable.

Updates #24352.

Change-Id: I0a45da6173b3dabebf42484bbbed30d9e5e20e01
Reviewed-on: https://go-review.googlesource.com/100058
Reviewed-by: Robert Griesemer <gri@golang.org>
Run-TryBot: Robert Griesemer <gri@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@gopherbot
Copy link

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

@gopherbot
Copy link

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

@gopherbot
Copy link

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

@gopherbot
Copy link

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

@jimmyfrasche
Copy link
Member Author

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
Copy link

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

@gopherbot
Copy link

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

gopherbot pushed a commit that referenced this issue Mar 19, 2018
@jimmyfrasche @griesemer
go/format: move example to external test file
1101a90 
Per #11257 all examples should be in external test files.

Additionally, doing so makes this example playable.

Updates #24352. (Albeit tangentially).

Change-Id: I77ab4655107f61db2e9d21a608b73ace3a230fb2
Reviewed-on: https://go-review.googlesource.com/101285
Reviewed-by: Robert Griesemer <gri@golang.org>
gopherbot pushed a commit that referenced this issue Mar 19, 2018
@jimmyfrasche @griesemer
go/constant: add examples for working with constant.Value
4b837c7 
Updates #24352.

Change-Id: Ie7c1de905154a483b7f7748de28e35b484cce6ea
Reviewed-on: https://go-review.googlesource.com/101279
Reviewed-by: Robert Griesemer <gri@golang.org>
Run-TryBot: Robert Griesemer <gri@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@gopherbot
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation help wanted
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@andybons @jimmyfrasche @griesemer @gopherbot