container/heap: better package documentation

Fixes #1820.

R=golang-dev, bradfitz, gri
CC=golang-dev
https://golang.org/cl/5540073

diff --git a/src/pkg/container/heap/heap.go b/src/pkg/container/heap/heap.go
index ca9113967548d2d463192ff117002527faa2eca1..7af636b45133c4b56df97cc19d37a0da866cb512 100644 (file)
--- a/src/pkg/container/heap/heap.go
+++ b/src/pkg/container/heap/heap.go
@@ -3,7 +3,13 @@
 // license that can be found in the LICENSE file.
 
 // Package heap provides heap operations for any type that implements
-// heap.Interface.
+// heap.Interface. A heap is a tree with the property that each node is the
+// highest-valued node in its subtree.
+//
+// A heap is a common way to impement a priority queue. To build a priority
+// queue, implement the Heap interface with the (negative) priority as the
+// ordering for the Less method, so Push adds items while Pop removes the
+// highest-priority item from the queue.
 //
 package heap