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, 21 insertions, 2 deletions

diff --git a/src/time/badlinkname.go b/src/time/badlinkname.go
index 96d2e31862..097a823ccf 100644
--- a/src/time/badlinkname.go
+++ b/src/time/badlinkname.go
@@ -13,5 +13,3 @@ import _ "unsafe"
 // in new code.
 
 //go:linkname absClock
-//go:linkname absDate
-//go:linkname nextStdChunk
diff --git a/src/time/format.go b/src/time/format.go
index c823bce4d8..07f1f804c1 100644
--- a/src/time/format.go
+++ b/src/time/format.go
@@ -7,6 +7,7 @@ package time
 import (
 	"errors"
 	"internal/stringslite"
+	_ "unsafe" // for linkname
 )
 
 // These are predefined layouts for use in [Time.Format] and [time.Parse].
@@ -184,6 +185,16 @@ func startsWithLowerCase(str string) bool {
 
 // nextStdChunk finds the first occurrence of a std string in
 // layout and returns the text before, the std string, and the text after.
+//
+// nextStdChunk 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/go
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname nextStdChunk
 func nextStdChunk(layout string) (prefix string, std int, suffix string) {
 	for i := 0; i < len(layout); i++ {
 		switch c := int(layout[i]); c {
diff --git a/src/time/time.go b/src/time/time.go
index 0bbdeaecf5..63ee6f6f94 100644
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -988,6 +988,16 @@ func (t Time) date(full bool) (year int, month Month, day int, yday int) {
 }
 
 // absDate is like date but operates on an absolute time.
+//
+// absDate should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - gitee.com/quant1x/gox
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname absDate
 func absDate(abs uint64, full bool) (year int, month Month, day int, yday int) {
 	// Split into time and day.
 	d := abs / secondsPerDay