gotypes: add a link to the 1.18 API guide, and fix links

Update the go/types guide to have a link to the new 1.18 API guide, for now. Also fix some links to pkg.go.dev and golang.org/x that were amended in the autogenerated README.md rather than the original source. For golang/go#50676 Change-Id: Ib98ed095d74be02046c426e51f1ae2b9ceb03b0d Reviewed-on: https://go-review.googlesource.com/c/example/+/389656 Trust: Robert Findley <rfindley@google.com> Run-TryBot: Robert Findley <rfindley@google.com> Reviewed-by: Robert Griesemer <gri@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
HadesHappy · Mar 4, 2022 · 3e2dd57 · 3e2dd57
1 parent f325e80
commit 3e2dd57
Show file tree

Hide file tree

Showing 8 changed files with 40 additions and 25 deletions.
diff --git a/gotypes/README.md b/gotypes/README.md
@@ -9,6 +9,7 @@ This document is maintained by Alan Donovan `adonovan@google.com`.
 
 # Contents
 
+1. [Changes in Go 1.18](#changes-in-go-1.18)
 1. [Introduction](#introduction)
 1. [An Example](#an-example)
 1. [Objects](#objects)
@@ -33,6 +34,13 @@ This document is maintained by Alan Donovan `adonovan@google.com`.
 1. [Formatting support](#formatting-support)
 1. [Getting from A to B](#getting-from-a-to-b)
 
+# Changes in Go 1.18
+
+Go 1.18 introduces generic Go code, and several corresponding new APIs for
+`go/types`. This document is not yet up-to-date for these changes, but a guide
+to the new changes exists at
+[`x/exp/typeparams/example`](https://github.com/golang/exp/tree/master/typeparams/example).
+
 # Introduction
 
 
@@ -995,7 +1003,7 @@ Use this function instead:
 
 
 For the same reason, you should not use a `Type` as a key in a map.
-The [`golang.org/x/tools/go/types/typeutil` package](https://godoc.org/golang.org/x/tools/go/types/typeutil)
+The [`golang.org/x/tools/go/types/typeutil` package](https://pkg.go.dev/golang.org/x/tools/go/types/typeutil)
 provides a map keyed by types that uses the correct
 equivalence relation.
 
@@ -2225,7 +2233,7 @@ function.
 
 Here's a typical invocation on the standard `encoding/xml` package.
 It reports a number of places where the 7-word
-[`StartElement` type](https://godoc.org/encoding/xml#StartElement)
+[`StartElement` type](https://pkg.go.dev/encoding/xml#StartElement)
 is copied.
 
 
@@ -2288,7 +2296,7 @@ ran a `go install` or `go build -i` command.
 
 
 
-The [`golang.org/tools/x/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader)
+The [`golang.org/tools/x/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader)
 provides an alternative `Importer` that addresses
 some of these problems.
 It loads a complete program from source, performing
@@ -2524,13 +2532,13 @@ of the form "I have an A; I need the corresponding B".
 
 To map **from a `token.Pos` to an `ast.Node`**, call the
 helper function
-[`astutil.PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval).
+[`astutil.PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval).
 It returns the enclosing `ast.Node`, and all its ancestors up to
 the root of the file.
 You must know which file `*ast.File` the `token.Pos` belongs to.
 Alternatively, you can search an entire program loaded by the
 `loader` package, using
-[`(*loader.Program).PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/loader#Program.PathEnclosingInterval).
+[`(*loader.Program).PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/loader#Program.PathEnclosingInterval).
 
 
 

diff --git a/gotypes/defsuses/main.go b/gotypes/defsuses/main.go
@@ -58,7 +58,7 @@ func main() {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/defsuses
+$ go build golang.org/x/example/gotypes/defsuses
 $ ./defsuses
 hello.go:1:9: "main" defines <nil>
 hello.go:5:6: "main" defines func hello.main()

diff --git a/gotypes/go-types.md b/gotypes/go-types.md
@@ -10,6 +10,13 @@ This document is maintained by Alan Donovan `adonovan@google.com`.
 
 %toc
 
+# Changes in Go 1.18
+
+Go 1.18 introduces generics, and several corresponding new APIs for `go/types`.
+This document is not yet up-to-date for these changes, but a guide to the new
+changes exists at
+[`x/exp/typeparams/example`](https://github.com/golang/exp/tree/master/typeparams/example).
+
 # Introduction
 
 
@@ -55,7 +62,7 @@ constant expressions, as we'll see in
 
 
 
-The [`golang.org/x/tools/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader)
+The [`golang.org/x/tools/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader)
 from the `x/tools` repository is a client of the type
 checker that loads, parses, and type-checks a complete Go program from
 source code.
@@ -110,7 +117,7 @@ the _hello, world_ program, supplied as a string.
 Later examples will be variations on this one, and we'll often omit
 boilerplate details such as parsing.
 To check out and build the examples,
-run `go get github.com/golang/example/gotypes/...`.
+run `go get golang.org/x/example/gotypes/...`.
 
 
 %include pkginfo/main.go
@@ -142,7 +149,7 @@ how to locate the imported packages.
 Here we use `importer.Default()`, which loads compiler-generated
 export data, but we'll explore alternatives in [Imports](#imports).
 
-	
+
 
 Fourth, the program calls `Check`.
 This creates a `Package` whose path is `"cmd/hello"`, and
@@ -602,7 +609,7 @@ by calling its `(*Func).Scope` method.
 
 
 <!--
-TODO: explain explicit and implicit blocks 
+TODO: explain explicit and implicit blocks
 TODO: explain Dot imports.
 TODO: explain that Func blocks are associated with FuncType (not FuncDecl or FuncLit)
 -->
@@ -668,7 +675,7 @@ does a name lookup at a specific position in that lexical block.
 
 
 
-A typical input is shown below. 
+A typical input is shown below.
 The first comment causes a lookup of `"append"` in the file block.
 The second comment looks up `"fmt"` in the `main` function's block,
 and so on.
@@ -814,7 +821,7 @@ Use this function instead:
 
 
 For the same reason, you should not use a `Type` as a key in a map.
-The [`golang.org/x/tools/go/types/typeutil` package](https://godoc.org/golang.org/x/tools/go/types/typeutil)
+The [`golang.org/x/tools/go/types/typeutil` package](https://pkg.go.dev/golang.org/x/tools/go/types/typeutil)
 provides a map keyed by types that uses the correct
 equivalence relation.
 
@@ -996,7 +1003,7 @@ The type checker builds the exact same data structures given this input:
 
 A similar issue applies to the methods of named interface types.
 
-					 
+
 ## Tuple Types
 
 
@@ -1230,7 +1237,7 @@ interface `v`, then the type assertion is not legal, as in this example:
 
 
 	// error: io.Writer is not assertible to int
-	func f(w io.Writer) int { return w.(int) } 
+	func f(w io.Writer) int { return w.(int) }
 
 
 
@@ -1443,7 +1450,7 @@ all.)
 
 
 The final two parameters of `LookupFieldOrMethod` are `(pkg
-*Package, name string)`.  
+*Package, name string)`.
 Together they specify the name of the field or method to look up.
 This brings us to `Id`s.
 
@@ -1654,7 +1661,7 @@ Constants are represented using the `Value` interface from the
 	package constant // go/constant
 
 	type Value interface {
-		Kind() Kind 
+		Kind() Kind
 	}
 
 	type Kind int // one of Unknown, Bool, String, Int, Float, Complex
@@ -1787,7 +1794,7 @@ function.
 
 Here's a typical invocation on the standard `encoding/xml` package.
 It reports a number of places where the 7-word
-[`StartElement` type](https://godoc.org/encoding/xml#StartElement)
+[`StartElement` type](https://pkg.go.dev/encoding/xml#StartElement)
 is copied.
 
 
@@ -1843,7 +1850,7 @@ ran a `go install` or `go build -i` command.
 
 
 
-The [`golang.org/tools/x/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader)
+The [`golang.org/tools/x/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader)
 provides an alternative `Importer` that addresses
 some of these problems.
 It loads a complete program from source, performing
@@ -2025,13 +2032,13 @@ of the form "I have an A; I need the corresponding B".
 
 To map **from a `token.Pos` to an `ast.Node`**, call the
 helper function
-[`astutil.PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval).
+[`astutil.PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval).
 It returns the enclosing `ast.Node`, and all its ancestors up to
 the root of the file.
 You must know which file `*ast.File` the `token.Pos` belongs to.
 Alternatively, you can search an entire program loaded by the
 `loader` package, using
-[`(*loader.Program).PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/loader#Program.PathEnclosingInterval).
+[`(*loader.Program).PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/loader#Program.PathEnclosingInterval).
 
 
 

diff --git a/gotypes/implements/main.go b/gotypes/implements/main.go
@@ -68,7 +68,7 @@ func main() {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/implements
+$ go build golang.org/x/example/gotypes/implements
 $ ./implements
 *hello.A satisfies hello.I
 hello.B satisfies hello.I

diff --git a/gotypes/lookup/lookup.go b/gotypes/lookup/lookup.go
@@ -65,7 +65,7 @@ func main() {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/lookup
+$ go build golang.org/x/example/gotypes/lookup
 $ ./lookup
 At hello.go:6:1,        "append" = builtin append
 At hello.go:8:9,        "fmt" = package fmt

diff --git a/gotypes/nilfunc/main.go b/gotypes/nilfunc/main.go
@@ -95,7 +95,7 @@ func CheckNilFuncComparison(info *types.Info, n ast.Node) {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/nilfunc
+$ go build golang.org/x/example/gotypes/nilfunc
 $ ./nilfunc
 input.go:7:5: comparison of function Bytes == nil is always false
 input.go:7:25: comparison of function Repeat != nil is always true

diff --git a/gotypes/pkginfo/main.go b/gotypes/pkginfo/main.go
@@ -52,7 +52,7 @@ func main() {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/pkginfo
+$ go build golang.org/x/example/gotypes/pkginfo
 $ ./pkginfo
 Package  "cmd/hello"
 Name:    main

diff --git a/gotypes/typeandvalue/main.go b/gotypes/typeandvalue/main.go
@@ -96,7 +96,7 @@ func mode(tv types.TypeAndValue) string {
 
 /*
 //!+output
-$ go build github.com/golang/example/gotypes/typeandvalue
+$ go build golang.org/x/example/gotypes/typeandvalue
 $ ./typeandvalue
 make(map[string]int)            mode:  value
                                 type:  map[string]int