all: document legacy //go:linkname for modules with ≥50,000 dependents

Note that this depends on the revert of CL 581395 to move zeroVal back.

For #67401.

Change-Id: I507c27c2404ad1348aabf1ffa3740e6b1957495b
Reviewed-on: https://go-review.googlesource.com/c/go/+/587217
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Russ Cox <rsc@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>

3 files changed, 37 insertions, 15 deletions

diff --git a/src/reflect/badlinkname.go b/src/reflect/badlinkname.go
index e8fb4ff8c6..e05208ead7 100644
--- a/src/reflect/badlinkname.go
+++ b/src/reflect/badlinkname.go
@@ -9,17 +9,26 @@ import (
 	_ "unsafe"
 )
 
-// As of Go 1.22, the symbols below are found to be pulled via
-// linkname in the wild. We provide a push linkname here, to
-// keep them accessible with pull linknames.
-// This may change in the future. Please do not depend on them
-// in new code.
+// Widely used packages access these symbols using linkname,
+// most notably:
+//	- github.com/goccy/go-json
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401
+// and go.dev/issue/67279.
 
 //go:linkname add
-//go:linkname ifaceIndir
-//go:linkname rtypeOff
-//go:linkname toType
 //go:linkname typesByString
+
+// ifaceIndir reports whether t is stored indirectly in an interface value.
+// It is no longer used by this package and is here entirely for the
+// linkname uses.
+//
+//go:linkname unusedIfaceIndir reflect.ifaceIndir
+func unusedIfaceIndir(t *abi.Type) bool {
+	return t.Kind_&abi.KindDirectIface == 0
+}
+
 //go:linkname valueInterface
 
 // The compiler doesn't allow linknames on methods, for good reasons.
diff --git a/src/reflect/type.go b/src/reflect/type.go
index 6ad2ace266..7789aa2f91 100644
--- a/src/reflect/type.go
+++ b/src/reflect/type.go
@@ -1632,6 +1632,15 @@ func haveIdenticalUnderlyingType(T, V *abi.Type, cmpTags bool) bool {
 // pointers, channels, maps, slices, and arrays.
 func typelinks() (sections []unsafe.Pointer, offset [][]int32)
 
+// rtypeOff should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/goccy/go-json
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname rtypeOff
 func rtypeOff(section unsafe.Pointer, off int32) *abi.Type {
 	return (*abi.Type)(add(section, uintptr(off), "sizeof(rtype) > 0"))
 }
@@ -2887,6 +2896,16 @@ func appendVarint(x []byte, v uintptr) []byte {
 // a nil *rtype must be replaced by a nil Type, but in gccgo this
 // function takes care of ensuring that multiple *rtype for the same
 // type are coalesced into a single Type.
+//
+// toType should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/goccy/go-json
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname toType
 func toType(t *abi.Type) Type {
 	if t == nil {
 		return nil
@@ -3031,10 +3050,3 @@ func TypeFor[T any]() Type {
 	}
 	return TypeOf((*T)(nil)).Elem() // only for an interface kind
 }
-
-// ifaceIndir reports whether t is stored indirectly in an interface value.
-// This function is no longer called by the reflect package,
-// and https://go.dev/issue/67279 tracks its deletion.
-func ifaceIndir(t *abi.Type) bool {
-	return t.Kind_&abi.KindDirectIface == 0
-}
diff --git a/src/reflect/value.go b/src/reflect/value.go
index 56d8ba708c..0854371ed4 100644
--- a/src/reflect/value.go
+++ b/src/reflect/value.go
@@ -3877,6 +3877,7 @@ func mapassign0(t *abi.Type, m unsafe.Pointer, key, val unsafe.Pointer)
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/modern-go/reflect2
+//   - github.com/goccy/go-json
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.