embed: update docs for proposal tweaks

//go:embed variables can be type aliases.

//go:embed variables can't be local to a function.

For #43216
For #43602
Fixes #43978

Change-Id: Ib1d104dfa32b97c91d8bfc5ed5d461ca14da188f
Reviewed-on: https://go-review.googlesource.com/c/go/+/288072
Trust: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>

1 files changed, 16 insertions, 6 deletions

diff --git a/src/embed/embed.go b/src/embed/embed.go
index cc6855e6a5b..f12bf31e767 100644
--- a/src/embed/embed.go
+++ b/src/embed/embed.go
@@ -9,18 +9,28 @@
 // files read from the package directory or subdirectories at compile time.
 //
 // For example, here are three ways to embed a file named hello.txt
-// and then print its contents at run time:
+// and then print its contents at run time.
 //
-//	import "embed"
+// Embedding one file into a string:
+//
+//	import _ "embed"
 //
 //	//go:embed hello.txt
 //	var s string
 //	print(s)
 //
+// Embedding one file into a slice of bytes:
+//
+//	import _ "embed"
+//
 //	//go:embed hello.txt
 //	var b []byte
 //	print(string(b))
 //
+// Embedded one or more files into a file system:
+//
+//	import "embed"
+//
 //	//go:embed hello.txt
 //	var f embed.FS
 //	data, _ := f.ReadFile("hello.txt")
@@ -34,8 +44,8 @@
 // The directive must immediately precede a line containing the declaration of a single variable.
 // Only blank lines and ‘//’ line comments are permitted between the directive and the declaration.
 //
-// The variable must be of type string, []byte, or FS exactly. Named types or type aliases
-// derived from those types are not allowed.
+// The type of the variable must be a string type, or a slice of a byte type,
+// or FS (or an alias of FS).
 //
 // For example:
 //
@@ -70,8 +80,8 @@
 //
 // The //go:embed directive can be used with both exported and unexported variables,
 // depending on whether the package wants to make the data available to other packages.
-// Similarly, it can be used with both global and function-local variables,
-// depending on what is more convenient in context.
+// It can only be used with global variables at package scope,
+// not with local variables.
 //
 // Patterns must not match files outside the package's module, such as ‘.git/*’ or symbolic links.
 // Matches for empty directories are ignored. After that, each pattern in a //go:embed line