doct: added examples to the stack revamped docs + small corrections

Author: lfenzo

docs/src/stack.md

@@ -6,10 +6,10 @@ DocTestSetup = :(using DataStructures)
 
 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` type is a light-weight wrapper around the
-[`Deque`](./deque.md) type.
+In DataStructures.jl the [`Stack`](./stack.md) type is a light-weight wrapper around
+the [`Deque`](./deque.md) type.
 
-!!! note "Note: Iterator interface"
+!!! 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

src/stack.jl

@@ -6,7 +6,7 @@ Create a `Stack` object containing elements of type `T` for Last In, First Out (
 
 # Parameters
 - `T::Type` Stack element data type.
-- `blksize::Integer` Unrolled linked-list bleck size (in bytes). Defualt = 1024.
+- `blksize::Integer` Unrolled linked-list bleck size (in bytes). Default = 1024.
 
 # Examples
 ```jldoctest
@@ -28,14 +28,43 @@ Stack{T}(blksize::Integer) where {T} = Stack(Deque{T}(blksize))
     isempty(s::Stack)
 
 Check if stack `s` is empty.
+
+# Example
+```jldoctest
+julia> s = Stack{Char}()
+Stack{Char}(Deque [Char[]])
+
+julia> isempty(s)
+true
+
+julia> for char in "racecar"
+           push!(s, char)
+       end
+
+julia> isempty(s)
+false
+```
 """
 Base.isempty(s::Stack) = isempty(s.store)
 
 
 """
-    isempty(s::Stack)
+    length(s::Stack)
 
 Return the number of elements in stack `s`.
+
+# Example
+```jldoctest
+julia> s = Stack{Char}()
+Stack{Char}(Deque [Char[]])
+
+julia> for char in "racecar"
+           push!(s, char)
+       end
+
+julia> length(s)
+7
+```
 """
 Base.length(s::Stack) = length(s.store)
 
@@ -44,49 +73,180 @@ Base.length(s::Stack) = length(s.store)
     eltype(::Type{Stack{T}}) where {T}
 
 Return the type of the elements in the stack.
+
+# Example
+```jldoctest
+julia> s = Stack{Float32}()
+Stack{Float32}(Deque [Float32[]])
+
+julia> eltype(s)
+Float32
+
+julia> eltype(s) <: Number
+true
+```
 """
 Base.eltype(::Type{Stack{T}}) where {T} = T
 
+
 """
     first(s::Stack)
 
-Get the top item from stack `s`. Also know as "peak".
+Get the first element of `s`. Since `s` is a stack, the first element will be the
+element at the top of `s` (also known as "peek" of the stack).
+
+# Example
+```jldoctest
+julia> s = Stack{Float32}()
+Stack{Float32}(Deque [Float32[]])
+
+julia> for i in range(1, 0.2, 5)
+           push!(s, i)
+       end
+
+julia> s
+Stack{Float32}(Deque [Float32[1.0, 0.8, 0.6, 0.4, 0.2]])
+
+julia> first(s)
+0.2f0
+```
 """
 Base.first(s::Stack) = last(s.store)
 
+"""
+    last(s::Stack)
+
+Get the last element of `s`. Since `s` is a stack, the last element will be the at
+bottom of the stack.
+
+# Example
+```jldoctest
+julia> s = Stack{Float32}()
+Stack{Float32}(Deque [Float32[]])
+
+julia> for i in range(1, 0.2, 5)
+           push!(s, i)
+       end
+
+julia> s
+Stack{Float32}(Deque [Float32[1.0, 0.8, 0.6, 0.4, 0.2]])
+
+julia> first(s)
+1.0f0
+```
+"""
 Base.last(s::Stack) = first(s.store)
 
+
 """
     push!(s::Stack, x)
 
 Insert new element `x` in top of stack `s`.
+
+# Example
+```jldoctest
+julia> s = Stack{Int}()
+Stack{Int64}(Deque [Int64[]])
+
+julia> push!(s, 42)
+Stack{Int64}(Deque [[42]])
+
+julia> push!(s, 314)
+Stack{Int64}(Deque [[42, 314]])
+```
 """
 function Base.push!(s::Stack, x)
     push!(s.store, x)
     return s
 end
 
+
 """
-   pop!(s::Stack) 
+    pop!(s::Stack) 
 
 Remove and return the top element from stack `s`.
+
+# Example
+```jldoctest
+julia> s = Stack{Int}()
+Stack{Int64}(Deque [Int64[]])
+
+julia> for i in 1:10
+           push!(s, i)
+       end
+
+julia> s
+Stack{Int64}(Deque [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])
+
+julia> popped = pop!(s)
+10
+
+julia> s
+Stack{Int64}(Deque [[1, 2, 3, 4, 5, 6, 7, 8, 9]])
+
+julia> popped
+10
+```
 """
 Base.pop!(s::Stack) = pop!(s.store)
 
+
 """
     empty!(s::Stack)
 
-Remove all elements from stack `s`.
+Make `s` empty by inplace-removing all its elements.
+
+# Example
+```jldoctest
+julia> s = Stack{Int}()
+Stack{Int64}(Deque [Int64[]])
+
+julia> for i in 1:4
+           push!(s, i)
+       end
+
+julia> isempty(s)
+false
+
+julia> empty!(s)
+Stack{Int64}(Deque [Int64[]])
+
+julia> isempty(s)
+true
+```
 """
 Base.empty!(s::Stack) = (empty!(s.store); s)
 
 Base.iterate(st::Stack, s...) = iterate(Iterators.reverse(st.store), s...)
 
 Iterators.reverse(s::Stack{T}) where {T} = DequeIterator{T}(s.store)
 
+
 """
     ==(x::Stack, y::Stack)
 
-Check if stacks `x` and `y` are equal in term of their contents.
+Check if stacks `x` and `y` are equal in term of their contents. Internally calls `==()`
+for each of the pairs formed by the elements of `x` and `y` in the order they appear
+in the stack.
+
+# Example
+```jldoctest
+julia> s1, s2 = Stack{String}(), Stack{String}()
+(Stack{String}(Deque [String[]]), Stack{String}(Deque [String[]]))
+
+julia> for string in ["foo", "bar", "42"]
+          push!(s1, string)
+          push!(s2, string)
+       end
+
+julia> s1 == s2
+true
+
+julia> pop!(s1)
+"42"
+
+julia> s1 == s2
+false
+```
 """
 Base.:(==)(x::Stack, y::Stack) = x.store == y.store