[dev.regabi] all: merge master (fca94ab) into dev.regabi

Conflicts:

- src/syscall/mksyscall.pl

Merge List:

+ 2021-02-02 fca94ab3ab spec: improve the example in Type assertions section
+ 2021-02-02 98f8454a73 cmd/link: don't decode type symbol in shared library in deadcode
+ 2021-02-02 1426a571b7 cmd/link: fix off-by-1 error in findShlibSection
+ 2021-02-01 32e789f4fb test: fix incorrectly laid out instructions in issue11656.go
+ 2021-02-01 0b6cfea634 doc/go1.16: document that on OpenBSD syscalls are now made through libc
+ 2021-02-01 26e29aa15a cmd/link: disable TestPIESize if CGO isn't enabled
+ 2021-02-01 6ac91e460c doc/go1.16: minor markup fixes
+ 2021-01-29 44361140c0 embed: update docs for proposal tweaks
+ 2021-01-29 68058edc39 runtime: document pointer write atomicity for memclrNoHeapPointers
+ 2021-01-28 c8bd8010ff syscall: generate readlen/writelen for openbsd libc
+ 2021-01-28 41bb49b878 cmd/go: revert TestScript/build_trimpath to use ioutil.ReadFile
+ 2021-01-28 725a642c2d runtime: correct syscall10/syscall10X on openbsd/amd64
+ 2021-01-28 4b068cafb5 doc/go1.16: document go/build/constraint package
+ 2021-01-28 376518d77f runtime,syscall: convert syscall on openbsd/arm64 to libc
+ 2021-01-27 00f2ff5c94 api/go1.16: add go/build/constraint APIs
+ 2021-01-27 35334caf18 crypto/x509: remove leftover CertificateRequest field
+ 2021-01-27 a5a5e2c968 runtime: make sure to remove open-coded defer entries in all cases after a recover
+ 2021-01-27 8cfa01943a runtime: block console ctrlhandler when the signal is handled
+ 2021-01-27 ff9e8364c6 cmd/go: skip issue33139 when the 'cc' script command is unavailable
+ 2021-01-27 cd176b3615 runtime: switch runtime to libc for openbsd/arm64
+ 2021-01-27 6c8fbfbdcf runtime: convert openbsd/arm64 locking to libc
+ 2021-01-27 5cdf0da1bf syscall: clean up mkasm related changes
+ 2021-01-27 210f70e298 doc/go1.16: fix closing brace in .Export format
+ 2021-01-27 0f797f168d math: fix typo in sqrt.go code comment
+ 2021-01-26 8634a234df runtime,syscall: convert syscall on openbsd/amd64 to libc
+ 2021-01-26 1d5e14632e os: further document limitations around naked file descriptors
+ 2021-01-26 cf263e9f77 os: correct names in CreateTemp and MkdirTemp doc comments
+ 2021-01-26 ce8b318624 net/http/fcgi: remove locking added to prevent a test-only race

Change-Id: I9e89df040dfbbeb50f4ce653a8da437cb72b3ef9

1 files changed, 16 insertions, 6 deletions

diff --git a/src/embed/embed.go b/src/embed/embed.go
index 26c3f2d604..5f984aaf71 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