Address english syntax and grammar based on vale's linter

Author: oleiade

Diff for: .gitignore

@@ -20,3 +20,5 @@ _cgo_export.*
 _testmain.go
 
 *.exe
+
+styles/

Diff for: .vale.ini

@@ -0,0 +1,9 @@
+StylesPath = styles
+
+MinAlertLevel = suggestion
+Vocab = Lane
+
+Packages = Google, proselint, write-good
+
+[*]
+BasedOnStyles = Vale, Google, proselint, write-good

Diff for: README.md

@@ -6,7 +6,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/oleiade/lane)](https://goreportcard.com/report/github.com/oleiade/lane)
 ![Go Version](https://img.shields.io/github/go-mod/go-version/oleiade/lane)
 
-The Lane package provides implementations of generic `Queue`, `PriorityQueue`, `Stack`, and `Deque` data structures. It was designed with simplicity, performance, and concurrent usage in mind.
+The Lane package provides implementations of generic `Queue`, `PriorityQueue`, `Stack`, and `Deque` data structures. Its design focuses on simplicity, performance, and concurrent usage.
 
 <!-- toc -->
 
@@ -15,14 +15,14 @@ The Lane package provides implementations of generic `Queue`, `PriorityQueue`, `
     - [Using `v2` releases](#using-v2-releases)
     - [Using `v1` releases](#using-v1-releases)
   - [Usage/Examples](#usageexamples)
-    - [Priority Queue](#priority-queue)
+    - [Priority queue](#priority-queue)
       - [Example](#example)
     - [Deque](#deque)
-      - [Deque Example](#deque-example)
+      - [Deque example](#deque-example)
     - [Queue](#queue)
-      - [Queue Example](#queue-example)
+      - [Queue example](#queue-example)
     - [Stack](#stack)
-      - [Stack Example](#stack-example)
+      - [Stack example](#stack-example)
   - [Performance](#performance)
   - [Documentation](#documentation)
   - [License](#license)
@@ -31,7 +31,7 @@ The Lane package provides implementations of generic `Queue`, `PriorityQueue`, `
 
 Using this package requires a working Go environment. [See the install instructions for Go](http://golang.org/doc/install.html).
 
-Go Modules are required when using this package. [See the go blog guide on using Go Modules](https://blog.golang.org/using-go-modules).
+This package requires a modern version of Go supporting modules: [see the go blog guide on using Go Modules](https://blog.golang.org/using-go-modules).
 
 ### Using `v2` releases
 
@@ -63,32 +63,31 @@ import (
 
 ## Usage/Examples
 
-### Priority Queue
+### Priority queue
 
-`PriorityQueue` is a _heap priority queue_ data structure implementation. It can be either maximum (descending) or minimum (ascending) oriented (ordered). Every operation on a `PriorityQueue` are synchronized and goroutine-safe. It performs `Push` and `Pop` operations in `O(log N)` time.
+`PriorityQueue` implements a _heap priority queue_ data structure. It can be either max (descending) or min (ascending) ordered. Every operation on a `PriorityQueue` is  goroutine-safe. It performs `Push` and `Pop` operations in *O(log N)* time.
 
 #### Example
 
 ```go
-// Let's create a new max ordered priority queue
-priorityQueue := lane.NewMaxPriorityQueue[string, int]()
+// Create a new max ordered priority queue
+priorityQueue := NewMaxPriorityQueue[string, int]()
 
 // And push some prioritized content into it
 priorityQueue.Push("easy as", 3)
 priorityQueue.Push("123", 2)
 priorityQueue.Push("do re mi", 4)
 priorityQueue.Push("abc", 1)
 
-// Now let's take a look at the min element in
+// Take a look at the min element in
 // the priority queue
 headValue, headPriority, ok := priorityQueue.Head()
 if ok {
     fmt.Println(headValue)    // "abc"
     fmt.Println(headPriority) // 1
 }
 
-// Okay the song order seems to be preserved, let's
-// roll
+// The operations seem to preserve the song order
 jacksonFive := make([]string, priorityQueue.Size())
 
 for i := 0; i < len(jacksonFive); i++ {
@@ -101,15 +100,15 @@ fmt.Println(strings.Join(jacksonFive, " "))
 
 ### Deque
 
-Deque is a _head-tail linked list data_ structure implementation. It is built upon a doubly-linked list container, and every operation on a `Deque` are performed in `O(1)` time complexity. Every operation on a `Deque` is synchronized and goroutine-safe.
+Deque implements a _head-tail linked list data_ structure. Built upon a doubly linked list container, every operation performed on a `Deque` happen in *O(1)* time complexity. Every operation on a `Deque` are goroutine-safe.
 
-Deques can optionally be instantiated with a limited capacity using the dedicated `NewBoundDeque` constructor, whereby the return value of the `Append` and `Prepend` return false if the Deque was full and the item was not added.
+Users have the option to instantiate Deques with a limited capacity using the dedicated `NewBoundDeque` constructor. When a bound Deque is full, the `Append` and `Prepend` operations fail.
 
-#### Deque Example
+#### Deque example
 
 ```go
-// Let's create a new deque data structure
-deque := lane.NewDeque[string]()
+// Create a new Deque data structure
+deque := NewDeque[string]()
 
 // And push some content into it using the Append
 // and Prepend methods
@@ -118,8 +117,8 @@ deque.Prepend("123")
 deque.Append("do re mi")
 deque.Prepend("abc")
 
-// Now let's take a look at what are the first and
-// last element stored in the Deque
+// Take a look at what the first and
+// last element stored in the Deque are.
 firstValue, ok := deque.First()
 if ok {
     fmt.Println(firstValue) // "abc"
@@ -130,7 +129,7 @@ if ok {
     fmt.Println(lastValue) // 1
 }
 
-// Okay now let's play with the Pop and Shift
+// Use the `Pop` and `Shift`
 // methods to bring the song words together
 jacksonFive := make([]string, deque.Size())
 
@@ -147,23 +146,22 @@ fmt.Println(strings.Join(jacksonFive, " "))
 
 ### Queue
 
-`Queue` is a **FIFO** (_First In First Out_) data structure implementation. It is built upon a `Deque` container and focuses its API on core functionalities: `Enqueue`, `Dequeue`, `Head`. Every operation's time complexity is O(1). Every operation on a `Queue` is synchronized and goroutine-safe.
+`Queue` is a **FIFO** (_First In First Out_) data structure implementation. Built upon a `Deque` container, it focuses its API on the following core functionalities: `Enqueue`, `Dequeue`, `Head`. Every operation on a Queue has a time complexity of *O(1)*. Every operation on a `Queue` is goroutine-safe.
 
-#### Queue Example
+#### Queue example
 
 ```go
-// Create a new queue and pretend we're handling starbucks
-// clients
-queue := lane.NewQueue[string]()
+// Create a new queue and pretend to handle Starbucks clients
+queue := NewQueue[string]()
 
-// Let's add the incoming clients to the queue
+// Add the incoming clients to the queue
 queue.Enqueue("grumpyClient")
 queue.Enqueue("happyClient")
 queue.Enqueue("ecstaticClient")
 
 fmt.Println(queue.Head()) // grumpyClient
 
-// Let's handle the clients asynchronously
+// Handle the clients asynchronously
 for {
     client, ok := queue.Dequeue()
     if !ok {
@@ -176,21 +174,22 @@ for {
 
 ### Stack
 
-`Stack` is a **LIFO** ( _Last in first out_ ) data structure implementation. It is built upon a `Deque` container and focuses its API on core functionalities: `Push`, `Pop`, `Head`. Every operation time complexity is O(1). Every operation on a `Stack` is synchronized and goroutine-safe.
+`Stack` implements a **Last In First Out** data structure. Built upon a `Deque` container, its API focuses on the following core functionalities: `Push`, `Pop`, `Head`. Every operation on a Stack has a time complexity of *O(1)*. Every operation on a `Stack` is goroutine-safe.
 
-#### Stack Example
+#### Stack example
 
 ```go
-stack := lane.NewStack[string]()
+// Create a new stack and put some plates over it
+stack := NewStack[string]()
 
-// Let's put some plates on the stack
+// Put some plates on the stack
 stack.Push("redPlate")
 stack.Push("bluePlate")
 stack.Push("greenPlate")
 
 fmt.Println(stack.Head()) // greenPlate
 
-// What's on top of the stack?
+// Check the top of the stack
 value, ok := stack.Pop()
 if ok {
     fmt.Println(value) // greenPlate
@@ -203,13 +202,13 @@ if ok {
     fmt.Println(value) // yellowPlate
 }
 
-// What's on top of the stack?
+// Check the top of the stack
 value, ok = stack.Pop()
 if ok {
     fmt.Println(value) // bluePlate
 }
 
-// What's on top of the stack?
+// Check the top of the stack
 value, ok = stack.Pop()
 if ok {
     fmt.Println(value) // redPlate

Diff for: deque.go

@@ -9,18 +9,18 @@ type Dequer[T any] interface {
 	Deque[T] | BoundDeque[T]
 }
 
-// Deque is a head-tail linked list data structure implementation.
+// Deque implements a head-tail linked list data structure.
 //
-// The Deque's implementation is built upon a doubly linked list
-// container, so that every operations' time complexity is O(1) (N.B:
-// linked-list are not CPU-cache friendly).
-// Every operation on a Deque are goroutine-safe and ready
+// Under the hood, the Deque's implementation is built upon a doubly linked list
+// container, so that every operation's time complexity is *O(1)*.
+// Every operation on a Deque is goroutine-safe and ready.
+//
+// Note that linked-list are not CPU-cache friendly).
 // for concurrent usage.
 type Deque[T any] struct {
 	sync.RWMutex
 
-	// container is the underlying storage container
-	// of deque's elements.
+	// The underlying storage container.
 	container *List[T]
 }
 
@@ -37,23 +37,23 @@ func NewDeque[T any](items ...T) *Deque[T] {
 	}
 }
 
-// Append inserts item at the back of the Deque in a O(1) time complexity.
+// Append inserts item at the back of the Deque in an *O(1)* time complexity.
 func (d *Deque[T]) Append(item T) {
 	d.Lock()
 	defer d.Unlock()
 
 	d.container.PushBack(item)
 }
 
-// Prepend inserts item at the Deque's front in a O(1) time complexity.
+// Prepend inserts item at the Deque's front in an *O(1)* time complexity.
 func (d *Deque[T]) Prepend(item T) {
 	d.Lock()
 	defer d.Unlock()
 
 	d.container.PushFront(item)
 }
 
-// Pop removes and returns the back element of the Deque in O(1) time complexity.
+// Pop removes and returns the back element of the Deque in an *O(1)* time complexity.
 func (d *Deque[T]) Pop() (item T, ok bool) {
 	d.Lock()
 	defer d.Unlock()
@@ -67,7 +67,7 @@ func (d *Deque[T]) Pop() (item T, ok bool) {
 	return
 }
 
-// Shift removes and returns the front element of the Deque in O(1) time complexity.
+// Shift removes and returns the front element of the Deque in *O(1)* time complexity.
 func (d *Deque[T]) Shift() (item T, ok bool) {
 	d.Lock()
 	defer d.Unlock()
@@ -81,7 +81,7 @@ func (d *Deque[T]) Shift() (item T, ok bool) {
 	return
 }
 
-// First returns the first value stored in the Deque in O(1) time complexity.
+// First returns the first value stored in the Deque in *O(1)* time complexity.
 func (d *Deque[T]) First() (item T, ok bool) {
 	d.RLock()
 	defer d.RUnlock()
@@ -95,7 +95,7 @@ func (d *Deque[T]) First() (item T, ok bool) {
 	return
 }
 
-// Last returns the last value stored in the Deque in O(1) time complexity.
+// Last returns the last value stored in the Deque in *O(1)* time complexity.
 func (d *Deque[T]) Last() (item T, ok bool) {
 	d.RLock()
 	defer d.RUnlock()
@@ -116,32 +116,32 @@ func (d *Deque[T]) Size() uint {
 	return d.container.Len()
 }
 
-// Empty checks if the deque is empty.
+// Empty checks if the Deque is empty.
 func (d *Deque[T]) Empty() bool {
 	d.RLock()
 	defer d.RUnlock()
 
 	return d.container.Len() == 0
 }
 
-// Capaciter is an interface type providing operations
-// related to capacity management.
-type Capaciter interface {
+// Capacitor defines operations related to capacity management.
+type Capacitor interface {
 	// Capacity returns the current capacity of the underlying type implementation.
 	Capacity() int
 
 	// IsFull returns whether the implementing type instance is full.
 	IsFull() bool
 }
 
-// BoundDeque is a head-tail linked list data structure implementation
-// with a user-defined capacity: any operation leading to the size
-// of the container to overflow its capacity will fail.
+// BoundDeque implements a head-tail linked list data structure
+// with a user-defined capacity. Once full, `Append` and `Prepend`
+// operations on a BoundedDeque fail.
+//
+// Under the hood, BoundDeque's implementation relies upon a doubly linked list
+// container. Thus, every operation on a BoundedDeque has a time complexity of *O(1)*.
+// Every operation on a BoundDeque is goroutine-safe.
 //
-// The BoundDeque's implementation is built upon a doubly linked list
-// container, so that every operations' time complexity is O(1) (N.B:
-// linked-list are not CPU-cache friendly).
-// Every operation on a BoundDeque are goroutine-safe and ready
+// Note that linked-list are not CPU-cache friendly).
 // for concurrent usage.
 type BoundDeque[T any] struct {
 	Deque[T]
@@ -159,42 +159,42 @@ func NewBoundDeque[T any](capacity uint, values ...T) *BoundDeque[T] {
 	}
 }
 
-// Capacity returns the BoundDeque's capacity.
-func (bd *BoundDeque[T]) Capacity() uint {
-	return bd.capacity
+// Capacity returns BoundDeque's capacity.
+func (d *BoundDeque[T]) Capacity() uint {
+	return d.capacity
 }
 
 // Full checks if the BoundDeque is full.
-func (bd *BoundDeque[T]) Full() bool {
-	return bd.container.Len() >= bd.capacity
+func (d *BoundDeque[T]) Full() bool {
+	return d.container.Len() >= d.capacity
 }
 
-// Append inserts item at the back of the BoundDeque in a O(1) time complexity.
-// If the BoundDeque's capacity disallows the insertion, Append returns false.
-func (bd *BoundDeque[T]) Append(item T) bool {
-	bd.Lock()
-	defer bd.Unlock()
+// Append inserts an item at the back of the BoundDeque in an *O(1)* time complexity.
+// If BoundDeque's capacity disallows the insertion, Append returns false.
+func (d *BoundDeque[T]) Append(item T) bool {
+	d.Lock()
+	defer d.Unlock()
 
-	if bd.Full() {
+	if d.Full() {
 		return false
 	}
 
-	bd.container.PushBack(item)
+	d.container.PushBack(item)
 
 	return true
 }
 
-// Prepend inserts item at the BoundDeque's front in a O(1) time complexity.
-// If the BoundDeque's capacity disallows the insertion, Prepend returns false.
-func (bd *BoundDeque[T]) Prepend(item T) bool {
-	bd.Lock()
-	defer bd.Unlock()
+// Prepend inserts item at the BoundDeque's front in an *O(1)* time complexity.
+// If BoundDeque's capacity disallows the insertion, Prepend returns false.
+func (d *BoundDeque[T]) Prepend(item T) bool {
+	d.Lock()
+	defer d.Unlock()
 
-	if bd.Full() {
+	if d.Full() {
 		return false
 	}
 
-	bd.container.PushFront(item)
+	d.container.PushFront(item)
 
 	return true
 }