container/heap: document what Push and Pop do

Now that vector is gone, there is no precedent to refer to.
This is a confusing point for people looking to use the
package.

R=golang-dev, r, cw
CC=golang-dev
https://golang.org/cl/5322069

src/pkg/container/heap/heap.go

@@ -11,14 +11,17 @@ import "sort"
 
 // Any type that implements heap.Interface may be used as a
 // min-heap with the following invariants (established after
-// Init has been called):
+// Init has been called or if the data is empty or sorted):
 //
 //	!h.Less(j, i) for 0 <= i < h.Len() and j = 2*i+1 or 2*i+2 and j < h.Len()
 //
+// Note that Push and Pop in this interface are for package heap's
+// implementation to call.  To add and remove things from the heap,
+// use heap.Push and heap.Pop.
 type Interface interface {
 	sort.Interface
-	Push(x interface{})
-	Pop() interface{}
+	Push(x interface{}) // add x as element Len()
+	Pop() interface{}   // remove and return element Len() - 1.
 }
 
 // A heap must be initialized before any of the heap operations