runtime: strongly encourage using CallersFrames over FuncForPC with Callers result

[cespare]

Go 1.7 introduced the CallersFrames API:

The new function CallersFrames translates a PC slice obtained from Callers into a sequence of frames corresponding to the call stack. This new API should be preferred instead of direct use of FuncForPC, because the frame sequence can more accurately describe call stacks with inlined function calls.

I understand that in Go 1.9, mid-stack inlining will make the results significantly worse for callers that are still using FuncForPC instead of CallersFrames. However, in the runtime documentation I don't see anything to steer the user towards one or the other.

Should we mark Func and FuncForPC as deprecated? Is there some situation to use them instead of CallersFrames?

@ianlancetaylor @aclements @davidlazar

[cespare]

(I guess that the Callers doc itself does say "To easily look up file/line information for the call sequence, use Frames.")

[aclements]

Yes, the documentation should definitely steer people more strongly in the right direction than it does now. Thanks for creating an issue to track this.

[gopherbot]

CL https://golang.org/cl/37726 mentions this issue.

[ianlancetaylor]

FuncForPC should not in general be used with values returned by Callers or Caller, but it is still meaningful and has no replacement for other uses. For example, the use in funcName and methodName in reflect/value.go is entirely legitimate.