Document + add tests for for mem.VirtualMemory()

This change changes and documents the (previously undocumented) behavior of Used
to "RAM used by programs".

We also remove the undocumented and unused Shared field of that struct.

So with this change in place, the VirtualMemoryStruct contains:
* three human-consumable fields for Total, Used and Available memory
* one human-consumable UsedPercentage field
* a number of kernel specific fields

mem/mem.go

@@ -4,18 +4,44 @@ import (
 	"encoding/json"
 )
 
+// Memory usage statistics. Total, Available and Used contain numbers of bytes
+// for human consumption.
+//
+// The other fields in this struct contain kernel specific values.
 type VirtualMemoryStat struct {
-	Total       uint64  `json:"total"`
-	Available   uint64  `json:"available"`
-	Used        uint64  `json:"used"`
+	// Total amount of RAM on this system
+	Total uint64 `json:"total"`
+
+	// RAM available for programs to allocate
+	//
+	// This value is computed from the kernel specific values.
+	Available uint64 `json:"available"`
+
+	// RAM used by programs
+	//
+	// This value is computed from the kernel specific values.
+	Used uint64 `json:"used"`
+
+	// Percentage of RAM used by programs
+	//
+	// This value is computed from the kernel specific values.
 	UsedPercent float64 `json:"used_percent"`
-	Free        uint64  `json:"free"`
-	Active      uint64  `json:"active"`
-	Inactive    uint64  `json:"inactive"`
-	Buffers     uint64  `json:"buffers"`
-	Cached      uint64  `json:"cached"`
-	Wired       uint64  `json:"wired"`
-	Shared      uint64  `json:"shared"`
+
+	// This is the kernel's notion of free memory; RAM chips whose bits nobody
+	// cares about the value of right now. For a human consumable number,
+	// Available is what you really want.
+	Free uint64 `json:"free"`
+
+	// OS X / BSD specific numbers:
+	// http://www.macyourself.com/2010/02/17/what-is-free-wired-active-and-inactive-system-memory-ram/
+	Active   uint64 `json:"active"`
+	Inactive uint64 `json:"inactive"`
+	Wired    uint64 `json:"wired"`
+
+	// Linux specific numbers
+	// https://www.centos.org/docs/5/html/5.1/Deployment_Guide/s2-proc-meminfo.html
+	Buffers uint64 `json:"buffers"`
+	Cached  uint64 `json:"cached"`
 }
 
 type SwapMemoryStat struct {

mem/mem_test.go

@@ -3,6 +3,8 @@ package mem
 import (
 	"fmt"
 	"testing"
+
+	"github.com/stretchr/testify/assert"
 )
 
 func TestVirtual_memory(t *testing.T) {
@@ -14,6 +16,21 @@ func TestVirtual_memory(t *testing.T) {
 	if v == empty {
 		t.Errorf("error %v", v)
 	}
+
+	assert.True(t, v.Total > 0)
+	assert.True(t, v.Available > 0)
+	assert.True(t, v.Used > 0)
+
+	assert.Equal(t, v.Total, v.Available+v.Used,
+		"Total should be computable from available + used: %v", v)
+
+	assert.True(t, v.Free > 0)
+	assert.True(t, v.Available > v.Free,
+		"Free should be a subset of Available: %v", v)
+
+	assert.InDelta(t, v.UsedPercent,
+		100*float64(v.Used)/float64(v.Total), 0.1,
+		"UsedPercent should be how many percent of Total is Used: %v", v)
 }
 
 func TestSwap_memory(t *testing.T) {
@@ -35,7 +52,7 @@ func TestVirtualMemoryStat_String(t *testing.T) {
 		UsedPercent: 30.1,
 		Free:        40,
 	}
-	e := `{"total":10,"available":20,"used":30,"used_percent":30.1,"free":40,"active":0,"inactive":0,"buffers":0,"cached":0,"wired":0,"shared":0}`
+	e := `{"total":10,"available":20,"used":30,"used_percent":30.1,"free":40,"active":0,"inactive":0,"wired":0,"buffers":0,"cached":0}`
 	if e != fmt.Sprintf("%v", v) {
 		t.Errorf("VirtualMemoryStat string is invalid: %v", v)
 	}