go/{ast,parser,types}: add signpost to golang.org/x/tools/go/packages

Change-Id: I5d5036e7b41df67d0c1ab42163fdceed8f9c42a3
Reviewed-on: https://go-review.googlesource.com/c/go/+/677137
Reviewed-by: Matt Proud <mtp@google.com>
Reviewed-by: Robert Griesemer <gri@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

src/go/ast/ast.go

@@ -4,6 +4,10 @@
 
 // Package ast declares the types used to represent syntax trees for Go
 // packages.
+//
+// Syntax trees may be constructed directly, but they are typically
+// produced from Go source code by the parser; see the ParseFile
+// function in package [go/parser].
 package ast
 
 import (

src/go/parser/parser.go

@@ -2,10 +2,14 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package parser implements a parser for Go source files. Input may be
-// provided in a variety of forms (see the various Parse* functions); the
-// output is an abstract syntax tree (AST) representing the Go source. The
-// parser is invoked through one of the Parse* functions.
+// Package parser implements a parser for Go source files.
+//
+// The [ParseFile] function reads file input from a string, []byte, or
+// io.Reader, and produces an [ast.File] representing the complete
+// abstract syntax tree of the file.
+//
+// The [ParseExprFrom] function reads a single source-level expression and
+// produces an [ast.Expr], the syntax tree of the expression.
 //
 // The parser accepts a larger language than is syntactically permitted by
 // the Go spec, for simplicity, and for improved robustness in the presence
@@ -13,6 +17,11 @@
 // treated like an ordinary parameter list and thus may contain multiple
 // entries where the spec permits exactly one. Consequently, the corresponding
 // field in the AST (ast.FuncDecl.Recv) field is not restricted to one entry.
+//
+// Applications that need to parse one or more complete packages of Go
+// source code may find it more convenient not to interact directly
+// with the parser but instead to use the Load function in package
+// [golang.org/x/tools/go/packages].
 package parser
 
 import (

src/go/types/api.go

@@ -26,6 +26,11 @@
 // specification. Use the Types field of [Info] for the results of
 // type deduction.
 //
+// Applications that need to type-check one or more complete packages
+// of Go source code may find it more convenient not to invoke the
+// type checker directly but instead to use the Load function in
+// package [golang.org/x/tools/go/packages].
+//
 // For a tutorial, see https://go.dev/s/types-tutorial.
 package types