From: Russ Cox <rsc@golang.org>
Date: Thu, 3 Nov 2011 19:30:57 +0000 (-0400)
Subject: container/heap: document what Push and Pop do
X-Git-Tag: weekly.2011-11-08~60
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=41dc7d3a99da6894110085e78c07e711f925948e;p=gostls13.git

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
---

diff --git a/src/pkg/container/heap/heap.go b/src/pkg/container/heap/heap.go
index 2dfe5b43ca..ca91139675 100644
--- a/src/pkg/container/heap/heap.go
+++ b/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