treewide: document linkname uses

These provide justification for each use of linkname. Poorly thought out uses of linkname are removed.

Signed-off-by: Ophestra <cat@gensokyo.uk>

cmd/hakurei/command.go

@@ -11,7 +11,7 @@ import (
 	"strconv"
 	"sync"
 	"time"
-	_ "unsafe"
+	_ "unsafe" // for go:linkname
 
 	"hakurei.app/command"
 	"hakurei.app/container/check"
@@ -24,8 +24,11 @@ import (
 	"hakurei.app/message"
 )
 
+// optionalErrorUnwrap calls [errors.Unwrap] and returns the resulting value
+// if it is not nil, or the original value if it is.
+//
 //go:linkname optionalErrorUnwrap hakurei.app/container.optionalErrorUnwrap
-func optionalErrorUnwrap(_ error) error
+func optionalErrorUnwrap(err error) error
 
 func buildCommand(ctx context.Context, msg message.Msg, early *earlyHardeningErrs, out io.Writer) command.Command {
 	var (

cmd/hakurei/json_test.go

@@ -1,18 +1,13 @@
-package main_test
+package main
 
 import (
-	"io"
 	"reflect"
 	"strings"
 	"testing"
-	_ "unsafe"
 
 	"hakurei.app/container/stub"
 )
 
-//go:linkname decodeJSON hakurei.app/cmd/hakurei.decodeJSON
-func decodeJSON(fatal func(v ...any), op string, r io.Reader, v any)
-
 func TestDecodeJSON(t *testing.T) {
 	t.Parallel()
 
@@ -62,9 +57,6 @@ func TestDecodeJSON(t *testing.T) {
 	}
 }
 
-//go:linkname encodeJSON hakurei.app/cmd/hakurei.encodeJSON
-func encodeJSON(fatal func(v ...any), output io.Writer, short bool, v any)
-
 func TestEncodeJSON(t *testing.T) {
 	t.Parallel()
 
@@ -74,7 +66,7 @@ func TestEncodeJSON(t *testing.T) {
 		want string
 	}{
 		{"marshaler", errorJSONMarshaler{},
-			`cannot encode json for main_test.errorJSONMarshaler: unique error 3735928559 injected by the test suite`},
+			`cannot encode json for main.errorJSONMarshaler: unique error 3735928559 injected by the test suite`},
 		{"default", func() {},
 			`cannot write json: json: unsupported type: func()`},
 	}