diff --git a/README.md b/README.md
index 715854a..3fe4785 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 
 Extremely fast ring-buffer deque ([double-ended queue](https://en.wikipedia.org/wiki/Double-ended_queue)) implementation.
 
-[![GoDoc](https://godoc.org/github.com/gammazero/deque?status.png)](https://godoc.org/github.com/gammazero/deque)
+[![GoDoc](https://godoc.org/github.com/gammazero/deque?status.svg)](https://godoc.org/github.com/gammazero/deque)
 
 This deque implementation is optimized for CPU and GC performance.  The circular buffer automatically re-sizes by powers of two, growing when additional capacity is needed and shrinking when only a quarter of the capacity is used, and uses bitwise arithmetic for all calculations.
 
diff --git a/deque.go b/deque.go
index 2d8933b..fb61e38 100644
--- a/deque.go
+++ b/deque.go
@@ -1,13 +1,15 @@
 /*
-Package deque provides a fast, ring-buffer deque (double-ended queue) that
-automatically re-sizes by powers of two.  This allows bitwise arithmetic for
-all calculations.  The ring-buffer implementation significantly improves memory
-and time performance with fewer GC pauses, compared to implementations based on
-slices and linked lists.
+Package deque provides a fast ring-buffer deque (double-ended queue)
+implementation.  The ring-buffer automatically re-sizes by powers of two,
+growing when additional capacity is needed and shrinking when only a quarter of
+the capacity is used, and uses bitwise arithmetic for all calculations.
+
+The ring-buffer implementation significantly improves memory and time
+performance with fewer GC pauses, compared to implementations based on slices
+and linked lists.
 
 For maximum speed, this deque implementation leaves concurrency safety up to
-the application to provide, however is best for the application if needed at
-all.
+the application to provide, however the application chooses, if needed at all.
 
 Queue (FIFO) operations are supported using PushBack() and PopFront().  Stack
 (LIFO) operations are supported using PushBack() and PopBack().
@@ -139,6 +141,8 @@ func (q *Deque) PeekAt(i int) interface{} {
 }
 
 // Clear removes all elements from the queue, but retains the current capacity.
+// The queue will not be resized smaller as long as items are only added.
+// Only when items are removed is the queue subject to getting resized smaller.
 func (q *Deque) Clear() {
 	// bitwise modulus
 	mbits := len(q.buf) - 1