common/prque: fix godoc comments (#29460)

Co-authored-by: Felix Lange <fjl@twurst.com>

common/prque/prque.go

@@ -22,7 +22,7 @@ import (
 	"container/heap"
 )
 
-// Priority queue data structure.
+// Prque is a priority queue data structure.
 type Prque[P cmp.Ordered, V any] struct {
 	cont *sstack[P, V]
 }
@@ -32,7 +32,7 @@ func New[P cmp.Ordered, V any](setIndex SetIndexCallback[V]) *Prque[P, V] {
 	return &Prque[P, V]{newSstack[P, V](setIndex)}
 }
 
-// Pushes a value with a given priority into the queue, expanding if necessary.
+// Push a value with a given priority into the queue, expanding if necessary.
 func (p *Prque[P, V]) Push(data V, priority P) {
 	heap.Push(p.cont, &item[P, V]{data, priority})
 }
@@ -43,14 +43,14 @@ func (p *Prque[P, V]) Peek() (V, P) {
 	return item.value, item.priority
 }
 
-// Pops the value with the greatest priority off the stack and returns it.
+// Pop the value with the greatest priority off the stack and returns it.
 // Currently no shrinking is done.
 func (p *Prque[P, V]) Pop() (V, P) {
 	item := heap.Pop(p.cont).(*item[P, V])
 	return item.value, item.priority
 }
 
-// Pops only the item from the queue, dropping the associated priority value.
+// PopItem pops only the item from the queue, dropping the associated priority value.
 func (p *Prque[P, V]) PopItem() V {
 	return heap.Pop(p.cont).(*item[P, V]).value
 }
@@ -60,17 +60,17 @@ func (p *Prque[P, V]) Remove(i int) V {
 	return heap.Remove(p.cont, i).(*item[P, V]).value
 }
 
-// Checks whether the priority queue is empty.
+// Empty checks whether the priority queue is empty.
 func (p *Prque[P, V]) Empty() bool {
 	return p.cont.Len() == 0
 }
 
-// Returns the number of element in the priority queue.
+// Size returns the number of element in the priority queue.
 func (p *Prque[P, V]) Size() int {
 	return p.cont.Len()
 }
 
-// Clears the contents of the priority queue.
+// Reset clears the contents of the priority queue.
 func (p *Prque[P, V]) Reset() {
 	*p = *New[P, V](p.cont.setIndex)
 }

common/prque/sstack.go

@@ -49,7 +49,7 @@ func newSstack[P cmp.Ordered, V any](setIndex SetIndexCallback[V]) *sstack[P, V]
 	return result
 }
 
-// Pushes a value onto the stack, expanding it if necessary. Required by
+// Push a value onto the stack, expanding it if necessary. Required by
 // heap.Interface.
 func (s *sstack[P, V]) Push(data any) {
 	if s.size == s.capacity {
@@ -69,7 +69,7 @@ func (s *sstack[P, V]) Push(data any) {
 	s.size++
 }
 
-// Pops a value off the stack and returns it. Currently no shrinking is done.
+// Pop a value off the stack and returns it. Currently no shrinking is done.
 // Required by heap.Interface.
 func (s *sstack[P, V]) Pop() (res any) {
 	s.size--
@@ -85,18 +85,18 @@ func (s *sstack[P, V]) Pop() (res any) {
 	return
 }
 
-// Returns the length of the stack. Required by sort.Interface.
+// Len returns the length of the stack. Required by sort.Interface.
 func (s *sstack[P, V]) Len() int {
 	return s.size
 }
 
-// Compares the priority of two elements of the stack (higher is first).
+// Less compares the priority of two elements of the stack (higher is first).
 // Required by sort.Interface.
 func (s *sstack[P, V]) Less(i, j int) bool {
 	return s.blocks[i/blockSize][i%blockSize].priority > s.blocks[j/blockSize][j%blockSize].priority
 }
 
-// Swaps two elements in the stack. Required by sort.Interface.
+// Swap two elements in the stack. Required by sort.Interface.
 func (s *sstack[P, V]) Swap(i, j int) {
 	ib, io, jb, jo := i/blockSize, i%blockSize, j/blockSize, j%blockSize
 	a, b := s.blocks[jb][jo], s.blocks[ib][io]
@@ -107,7 +107,7 @@ func (s *sstack[P, V]) Swap(i, j int) {
 	s.blocks[ib][io], s.blocks[jb][jo] = a, b
 }
 
-// Resets the stack, effectively clearing its contents.
+// Reset the stack, effectively clearing its contents.
 func (s *sstack[P, V]) Reset() {
 	*s = *newSstack[P, V](s.setIndex)
 }