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>

1 files changed, 19 insertions, 7 deletions

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
-}