Merge pull request JuliaCollections#809 from lfenzo/docs-revamp-stack-and-queue

Improved Queue and Stack Documentation + docstrings

Author: oxinabox

docs/make.jl

@@ -10,7 +10,8 @@ makedocs(
         "deque.md",
         "circ_buffer.md",
         "circ_deque.md",
-        "stack_and_queue.md",
+        "stack.md",
+        "queue.md",
         "priority-queue.md",
         "fenwick.md",
         "accumulators.md",

docs/src/queue.md

@@ -0,0 +1,50 @@
+```@meta
+DocTestSetup = :(using DataStructures)
+```
+
+# Queue
+
+The Queue data structure, also known as *First In, First Out* (FIFO) queue, allows
+addition and deletion of items in opposite ends of the data structure. Insertion is
+performed in the back of the queue while deletion is performed in the front of the
+queue. In DataStructures.jl, the `Queue` type is a light-weight wrapper around the
+[Deque](./deque.md) type.
+
+Queues are often used as a base for many different data structures, some of its
+variations implemented by DataStructures.jl include:
+
+- [Double Ended Queues](./deque.md)
+- [Circular Double Ended Queues](./circ_deque.md)
+- [Priority Queues](./priority-queue.md)
+
+## Constructors
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/queue.jl"]
+Order = [:type]
+```
+
+## Usage
+
+The `Queue` type implements the following methods:
+
+- [`eltype(::Type{Queue{T}}) where {T}`](@ref)
+- [`first(q::Queue)`](@ref)
+- [`isempty(q::Queue)`](@ref)
+- [`length(q::Queue)`](@ref)
+- [`last(q::Queue)`](@ref)
+- [`push!(q::Queue, x)`](@ref)
+- [`popfirst!(q::Queue)`](@ref)
+
+-----------
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/queue.jl"]
+Order = [:function]
+```
+
+```@meta
+DocTestSetup = nothing
+```

docs/src/stack.md

@@ -0,0 +1,75 @@
+```@meta
+DocTestSetup = :(using DataStructures)
+```
+
+# Stack
+
+The Stack data structure corresponds to a *Last In, First Out* (LIFO) queue in 
+which elements are added to and removed from only one of the ends of the queue.
+In DataStructures.jl the [`Stack`](./stack.md) type is a light-weight wrapper around
+the [`Deque`](./deque.md) type.
+
+!!! note "Notes on the Iterator interface implemented by the Stack"
+    The `Stack` type implements the Julia Iterator interface; iterating
+    over `Stack` returns items in *First In, Last Out* (FILO) order, i.e. "from top
+    to bottom" of the stack. There is also a `Iterators.reverse` function which
+    iterates over the items in *First In, First Out* (FIFO) order, or "from bottom
+    to top" of the stack.
+
+    ```jldoctest
+    julia> s = Stack{Int64}()
+    Stack{Int64}(Deque [Int64[]])
+
+    julia> for i in 1:4
+               push!(s, i)
+           end
+
+    julia> for el in s # top to bottom iteration 
+               println(el)
+           end
+    4
+    3
+    2
+    1
+
+    julia> for el in Iterators.reverse(s) # bottom to top iteration 
+               println(el)
+           end
+    1
+    2
+    3
+    4
+    ```
+
+## Constructors
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/stack.jl"]
+Order = [:type]
+```
+
+## Usage
+
+The `Stack` type implements the following methods:
+
+- [`==(x::Stack, y::Stack)`](@ref)
+- [`eltype(::Type{Stack{T}}) where {T}`](@ref)
+- [`empty!(s::Stack)`](@ref)
+- [`first(s::Stack)`](@ref)
+- [`isempty(s::Stack)`](@ref)
+- [`length(s::Stack)`](@ref)
+- [`pop!(s::Stack)`](@ref)
+- [`push!(s::Stack, x)`](@ref)
+
+----------
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/stack.jl"]
+Order = [:function]
+```
+
+```@meta
+DocTestSetup = nothing
+```

docs/src/stack_and_queue.md

@@ -1,9 +1,24 @@
 # FIFO queue
 
 """
+    Queue{T}() where {T}
     Queue{T}([blksize::Integer=1024])
 
-Create a `Queue` object containing elements of type `T`.
+Create a `Queue` object containing elements of type `T` for First In, First Out (FIFO) access.
+
+# Parameters
+
+- `T::Type` Queue element data type.
+- `blksize::Integer=1024` Unrolled linked-list bleck size (in bytes). Defualt = 1024.
+
+# Examples
+```jldoctest
+julia> q_int = Queue{Int64}() # create a queue with int elements
+Queue{Int64}(Deque [Int64[]])
+
+julia> q_float = Queue{Float64}() # create a queue with float elements
+Queue{Float64}(Deque [Float64[]])
+```
 """
 mutable struct Queue{T}
     store::Deque{T}
@@ -12,30 +27,63 @@ end
 Queue{T}() where {T} = Queue(Deque{T}())
 Queue{T}(blksize::Integer) where {T} = Queue(Deque{T}(blksize))
 
-Base.isempty(s::Queue) = isempty(s.store)
-Base.length(s::Queue) = length(s.store)
-Base.eltype(::Type{Queue{T}}) where T = T
+"""
+    isempty(q::Queue)
+
+Check if queue `q` is empty.
+"""
+Base.isempty(q::Queue) = isempty(q.store)
+
+"""
+    length(q::Queue)
+
+Return the number of elements in queue `q`.
+"""
+Base.length(q::Queue) = length(q.store)
+
+"""
+    eltype(::Type{Queue{T}}) where {T}
+
+Return the type of the elements in the queue.
+"""
+Base.eltype(::Type{Queue{T}}) where {T} = T
+
+"""
+    first(q::Queue)
+
+Get the first item from queue `q`.
+"""
+Base.first(q::Queue) = first(q.store)
+
+"""
+    last(q::Queue)
 
-Base.first(s::Queue) = first(s.store)
+Get the last element in queue `q`.
+"""
 Base.last(s::Queue) = last(s.store)
 
 """
-    push!(s::Queue, x)
+    push!(q::Queue, x)
 
-Inserts the value `x` to the end of the queue `s`.
+Inserts the value `x` to the end of the queue `q`.
 """
-function Base.push!(s::Queue, x)
-    push!(s.store, x)
-    return s
+function Base.push!(q::Queue, x)
+    push!(q.store, x)
+    return q
 end
 
 """
-    popfirst!(s::Queue)
+    popfirst!(q::Queue)
 
-Removes an element from the front of the queue `s` and returns it.
+Removes an element from the front of the queue `q` and returns it.
 """
 Base.popfirst!(s::Queue) = popfirst!(s.store)
 
+"""
+    empty!(q::Queue)
+
+Removes all elements from queue `q`.
+"""
 Base.empty!(s::Queue) = (empty!(s.store); s)
 
 # Iterators
@@ -44,4 +92,9 @@ Base.iterate(q::Queue, s...) = iterate(q.store, s...)
 
 Iterators.reverse(q::Queue) = Iterators.reverse(q.store)
 
+"""
+    ==(x::Queue, y::Queue)
+
+Verify if queues `x` and `y` are equivalent in their contents.
+"""
 Base.:(==)(x::Queue, y::Queue) = x.store == y.store