all: document legacy //go:linkname for modules with ≥200 dependents

Ignored these linknames which have not worked for a while:

github.com/xtls/xray-core:
	context.newCancelCtx removed in CL 463999 (Feb 2023)

github.com/u-root/u-root:
	funcPC removed in CL 513837 (Jul 2023)

tinygo.org/x/drivers:
	net.useNetdev never existed

For #67401.

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

3 files changed, 58 insertions, 6 deletions

diff --git a/src/net/http/badlinkname.go b/src/net/http/badlinkname.go
index 98726b1071..c714edf5f2 100644
--- a/src/net/http/badlinkname.go
+++ b/src/net/http/badlinkname.go
@@ -12,12 +12,6 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
-//go:linkname cloneMultipartFileHeader
-//go:linkname cloneMultipartForm
-//go:linkname cloneOrMakeHeader
-//go:linkname cloneTLSConfig
-//go:linkname cloneURL
-//go:linkname cloneURLValues
 //go:linkname newBufioReader
 //go:linkname newBufioWriterSize
 //go:linkname putBufioReader
diff --git a/src/net/http/clone.go b/src/net/http/clone.go
index 3a3375bff7..71f4242273 100644
--- a/src/net/http/clone.go
+++ b/src/net/http/clone.go
@@ -8,8 +8,18 @@ import (
 	"mime/multipart"
 	"net/textproto"
 	"net/url"
+	_ "unsafe" // for linkname
 )
 
+// cloneURLValues should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneURLValues
 func cloneURLValues(v url.Values) url.Values {
 	if v == nil {
 		return nil
@@ -19,6 +29,15 @@ func cloneURLValues(v url.Values) url.Values {
 	return url.Values(Header(v).Clone())
 }
 
+// cloneURL should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneURL
 func cloneURL(u *url.URL) *url.URL {
 	if u == nil {
 		return nil
@@ -32,6 +51,15 @@ func cloneURL(u *url.URL) *url.URL {
 	return u2
 }
 
+// cloneMultipartForm should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneMultipartForm
 func cloneMultipartForm(f *multipart.Form) *multipart.Form {
 	if f == nil {
 		return nil
@@ -53,6 +81,15 @@ func cloneMultipartForm(f *multipart.Form) *multipart.Form {
 	return f2
 }
 
+// cloneMultipartFileHeader should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneMultipartFileHeader
 func cloneMultipartFileHeader(fh *multipart.FileHeader) *multipart.FileHeader {
 	if fh == nil {
 		return nil
@@ -65,6 +102,16 @@ func cloneMultipartFileHeader(fh *multipart.FileHeader) *multipart.FileHeader {
 
 // cloneOrMakeHeader invokes Header.Clone but if the
 // result is nil, it'll instead make and return a non-nil Header.
+//
+// cloneOrMakeHeader should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneOrMakeHeader
 func cloneOrMakeHeader(hdr Header) Header {
 	clone := hdr.Clone()
 	if clone == nil {
diff --git a/src/net/http/transport.go b/src/net/http/transport.go
index 0d4332c344..a1ff7ebe32 100644
--- a/src/net/http/transport.go
+++ b/src/net/http/transport.go
@@ -30,6 +30,7 @@ import (
 	"sync"
 	"sync/atomic"
 	"time"
+	_ "unsafe"
 
 	"golang.org/x/net/http/httpguts"
 	"golang.org/x/net/http/httpproxy"
@@ -2983,6 +2984,16 @@ func (fakeLocker) Unlock() {}
 // cloneTLSConfig returns a shallow clone of cfg, or a new zero tls.Config if
 // cfg is nil. This is safe to call even if cfg is in active use by a TLS
 // client or server.
+//
+// cloneTLSConfig should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/searKing/golang
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cloneTLSConfig
 func cloneTLSConfig(cfg *tls.Config) *tls.Config {
 	if cfg == nil {
 		return &tls.Config{}