crypto/rsa: PublicKey.Equal() should say it expects a pointer

[glad-dev]

What version of Go are you using (go version)?

$ go version
go version go1.17 linux/amd64

Does this issue reproduce with the latest release?

N/A

What operating system and processor architecture are you using (go env)?

N/A but included below

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/bernd/.cache/go-build"
GOENV="/home/bernd/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/bernd/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/bernd/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/local/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.17"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/mnt/c/Users/User/Programming/Go/playground/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build1064618544=/tmp/go-build -gno-record-gcc-switches"

What did you do?

N/A

What did you expect to see?

I expected the documentation or the function signature to mention that publicKey.Equal expects a pointer instead of a value.

What did you see instead?

Neither the function signature nor the documentation makes it clear that publicKey.Equal expects a pointer instead of a value

[seankhliao]

cc @FiloSottile

[gopherbot]

Change https://go.dev/cl/532335 mentions this issue: crypto/rsa: PublicKey.Equal() documentation specifies that it requires a pointer

[randall77]

I'm confused by the confusion here. Sure, it is a mistake to pass a rsa.PublicKey instead of a *rsa.PublicKey to Equal. But how are you coming up with that rsa.PublicKey value? It is going to be useless in lots of places, not just as an argument to crypto/rsa.PublicKey.Equal. It doesn't have any methods and everything that might use it as a public key would barf on it.