runtime: document the behaviour of Caller and Callers when used in deferred functions

[ainar-g]

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

go version go1.10 linux/amd64

Does this issue reproduce with the latest release?

Yes, I've tried on b001ffb.

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

GOARCH="amd64"
GOBIN=""
GOCACHE="/home/ainar/.cache/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/ainar/go"
GORACE=""
GOROOT="/home/ainar/go/go1.10"
GOTMPDIR=""
GOTOOLDIR="/home/ainar/go/go1.10/pkg/tool/linux_amd64"
GCCGO="/usr/bin/gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
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-build197597232=/tmp/go-build -gno-record-gcc-switches"

What did you do?

https://play.golang.org/p/Jz6y0GkqTNW

What did you expect to see?

Either

    direct: main.go:11
  deferred: main.go:10

Or the documentation of runtime.Caller mentioning that deferred functions have line numbers that point to the line after return.

What did you see instead?

    direct: main.go:11
  deferred: main.go:12

And no mention of defer in runtime.Caller or runtime.Callers docs.

I understand why it's that way, and I've even created a wonky workaround (on Russian SO, on Playground). But I think that it would be good to mention this behaviour and basic reasoning behind it in the functions' docs.

[ianlancetaylor]

Documenting this briefly is fine. I just want to comment that I think the current behavior makes sense. The deferred function is not called at the point of the defer statement. That is where the call is deferred, not where it is made. The deferred function is actually called at the point where the deferring function returns. And that is what runtime.Caller reports.

[ainar-g]

@ianlancetaylor What about panic? E.g. https://play.golang.org/p/LcG_3IOEyr7. I would expect that deferred prints the line where panic was called, similar to return. Instead it prints asm_amd64.s:459, which doesn't seem helpful.

Is the behaviour for Caller even defined here? Should I report a separate issue about it?

[ianlancetaylor]

I have to agree that printing asm_amd64.s:459 is pointless. We should fix that if we can.

[ainar-g]

Filed #26320 about the panic one.