runtime: document MemStats better

[aclements]

The current runtime.MemStats documentation is terse and impenetrable. Questions about the meanings of these fields come up not infrequently. We should improve its documentation so that it actually explains what the fields mean as well as enough of the allocation model to understand their meanings and apply them to debugging.

/cc @RLH @hyangah

[hyangah]

additionally, would be nice if the documentation explains how they relate (or not relate) to pprof heap profile result.

[mberhault]

one example among many: from looking through mheap.go, it looks like none of the counters are decremented when memory is released to the system. Specifically, HeapIdle looks like it really should, and HeapSys may or may not depending on whether it's supposed to be "total memory obtained from the system", or "current mem ...".

[ianlancetaylor]

Postponing to 1.8.

[gopherbot]

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

[aclements]

additionally, would be nice if the documentation explains how they relate (or not relate) to pprof heap profile result.

I'm not sure where to put this that would make sense and people would see it. We do document in runtime/pprof that profiles are as of the most recently completed GC. I've added a blurb to ReadMemStats to clarify that it's instantaneous and to contrast it with profiles, but I don't know if it'll do any good.

[gopherbot]

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