runtime: update docs for MemStats.PauseNs

PauseNs is a circular buffer of recent pause times, and the
most recent one is at [((NumGC-1)+256)%256].

   Also fix comments cross-linking the Go and C definition of
various structs.

R=golang-dev, rsc, bradfitz
CC=golang-dev
https://golang.org/cl/6657047

src/pkg/runtime/malloc.goc

@@ -19,7 +19,7 @@ package runtime
 #pragma dataflag 16 /* mark mheap as 'no pointers', hiding from garbage collector */
 MHeap runtime·mheap;
 
-extern MStats mstats;	// defined in extern.go
+extern MStats mstats;	// defined in zruntime_def_$GOOS_$GOARCH.go
 
 extern volatile intgo runtime·MemProfileRate;
 

src/pkg/runtime/malloc.h

@@ -198,7 +198,7 @@ void	runtime·FixAlloc_Free(FixAlloc *f, void *p);
 
 
 // Statistics.
-// Shared with Go: if you edit this structure, also edit extern.go.
+// Shared with Go: if you edit this structure, also edit type MemStats in mem.go.
 struct MStats
 {
 	// General statistics.

src/pkg/runtime/mem.go

@@ -6,6 +6,9 @@ package runtime
 
 import "unsafe"
 
+// Note: the MemStats struct should be kept in sync with 
+// struct MStats in malloc.h
+
 // A MemStats records statistics about the memory allocator.
 type MemStats struct {
 	// General statistics.
@@ -39,7 +42,7 @@ type MemStats struct {
 	NextGC       uint64 // next run in HeapAlloc time (bytes)
 	LastGC       uint64 // last run in absolute time (ns)
 	PauseTotalNs uint64
-	PauseNs      [256]uint64 // most recent GC pause times
+	PauseNs      [256]uint64 // circular buffer of recent GC pause times, most recent at [(NumGC+255)%256]
 	NumGC        uint32
 	EnableGC     bool
 	DebugGC      bool

src/pkg/runtime/mprof.goc

@@ -307,8 +307,7 @@ runtime·blockevent(int64 cycles, int32 skip)
 	runtime·unlock(&proflock);
 }
 
-// Go interface to profile data.  (Declared in extern.go)
+// Go interface to profile data.  (Declared in debug.go)
-// Assumes Go sizeof(int) == sizeof(int32)
 
 // Must match MemProfileRecord in debug.go.
 typedef struct Record Record;