Repository: JuliaCollections/DataStructures.jl
Pull request #552 (2019-11-13 12:11:59)

Improved docstrings in stack.jl
Improved docstrings in stack.jl

codecov[bot]: # [Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=h1) Report
> Merging [#552](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=desc) into [master](https://codecov.io/gh/JuliaCollections/DataStructures.jl/commit/3d68cd3af77f327e828c976139e4996471804f3e?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552/graphs/tree.svg?width=650&token=7FHvoCSQ7k&height=150&src=pr)](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master     #552   +/-   ##
=======================================
  Coverage   87.82%   87.82%           
=======================================
  Files          32       32           
  Lines        2086     2086           
=======================================
  Hits         1832     1832           
  Misses        254      254
```


| [Impacted Files](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [src/stack.jl](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552/diff?src=pr&el=tree#diff-c3JjL3N0YWNrLmps) | `100% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=footer). Last update [3d68cd3...116fcae](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/552?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

scls19fr: hi @AtsushiSakai

maybe this improved docstrings could be included in documentation also. 
oxinabox: Are you sure those docstrings for `iterate` and `reverse_iter` are correct?
Can you add an example for them?
oxinabox: The `iterate` docstring is redudeant and misleading.
It doesn't return an FILO iterator -- the stack is FILO iterator,
`iterate` steps through processing that iterator,
which is what it does normally.

It might be worth mentioning that a `Stack` iterates `FILO`,
but it probably doesn't need a docstring on `iterate`.

```
julia> stack = Stack{Int}()
Stack{Int64}(Deque [Int64[]])

julia> push!(stack, 1); push!(stack, 2); push!(stack, 3)
Stack{Int64}(Deque [[1, 2, 3]])

julia> iterate(stack)
(3, (DataStructures.DequeBlock{Int64}(capa = 1024, front = 1, back
 = 3): [1, 2, 3], 2))

julia> collect(iterate(stack))
2-element Array{Any,1}:
 3
  (DataStructures.DequeBlock{Int64}(capa = 1024, front = 1, back = 3): [1, 2, 3], 2)

julia> collect(stack)
3-element Array{Int64,1}:
 3
 2
 1

julia> reverse_iter(stack)
DataStructures.DequeIterator{Int64}(Deque [[1, 2, 3]])

julia> collect(reverse_iter(stack))
3-element Array{Any,1}:
 1
 2
 3

```
AtsushiSakai: @scls19fr Hi. I updated the docs of stack.jl. Could you please check it?
AtsushiSakai: @oxinabox Thank you for your comment. I understood. I removed the docstring of iterate. 

Patch:
diff --git a/Project.toml b/Project.toml
index e6875c9..79f4203 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "DataStructures"
 uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
-version = "0.17.5"
+version = "0.17.6"
 
 [deps]
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
diff --git a/docs/src/stack_and_queue.md b/docs/src/stack_and_queue.md
index db1b0a3..cc805be 100644
--- a/docs/src/stack_and_queue.md
+++ b/docs/src/stack_and_queue.md
@@ -6,10 +6,17 @@ type, which respectively provide interfaces for LIFO and FIFO access.
 Usage of Stack:
 
 ```julia
-s = Stack{Int}()
-push!(s, x)
-x = top(s)
-x = pop!(s)
+s = Stack{Int}()            # create a stack
+isempty(s)                  # check whether the stack is empty
+length(s)                   # get the number of elements
+eltype(s)                   # get the type of elements
+push!(s, 1)                 # push back a item
+top(s)                      # get a first item
+pop!(s)                     # get and remove a first item
+empty!(s)                   # make a stack empty
+iterate(s::Stack)           # Get a LIFO iterator of a stack
+reverse_iter(s::Stack{T})   # Get a FILO iterator of a stack
+s1 == s2                    # check whether the two stacks are same
 ```
 
 Usage of Queue:
diff --git a/src/accumulator.jl b/src/accumulator.jl
index d414c0e..ba34101 100644
--- a/src/accumulator.jl
+++ b/src/accumulator.jl
@@ -7,9 +7,10 @@ end
 ## constructors
 
 Accumulator{T, V}() where {T,V<:Number} = Accumulator{T,V}(Dict{T,V}())
+Accumulator(map::AbstractDict) = Accumulator(Dict(map))
 
 counter(T::Type) = Accumulator{T,Int}()
-counter(dct::Dict{T,V}) where {T,V<:Integer} = Accumulator{T,V}(copy(dct))
+counter(dct::AbstractDict{T, V}) where {T, V<:Integer} = Accumulator{T, V}(Dict(dct))
 
 """
     counter(seq)
diff --git a/src/stack.jl b/src/stack.jl
index cd8d1ef..8259ca9 100644
--- a/src/stack.jl
+++ b/src/stack.jl
@@ -1,5 +1,29 @@
-# stacks
+"""
+    Stack{T}
 
+a Stack for Last In First Out(LIFO) access
+
+# Examples
+```jldoctest
+julia> s = Stack{Int}() # create a stack
+Stack{Int64}(Deque [Int64[]])
+
+julia> push!(s, 1) # push back a item
+Stack{Int64}(Deque [[1]])
+
+julia> x = top(s) # get a first item
+1
+
+julia> length(s)
+1
+
+julia> x = pop!(s) # get and remove a first item
+1
+
+julia> length(s)
+0
+```
+"""
 mutable struct Stack{T}
     store::Deque{T}
 end
@@ -11,6 +35,11 @@ isempty(s::Stack) = isempty(s.store)
 length(s::Stack) = length(s.store)
 Base.eltype(::Type{Stack{T}}) where T = T
 
+"""
+    top(s::Stack)
+
+Get a top item from a stack
+"""
 top(s::Stack) = back(s.store)
 
 function push!(s::Stack, x)
@@ -24,6 +53,11 @@ empty!(s::Stack) = (empty!(s.store); s)
 
 iterate(st::Stack, s...) = iterate(reverse_iter(st.store), s...)
 
+"""
+    reverse_iterate(s::Stack)
+
+Get a FILO iterator of a stack
+"""
 reverse_iter(s::Stack{T}) where {T} = DequeIterator{T}(s.store)
 
 ==(x::Stack, y::Stack) = x.store == y.store


Test patch:
diff --git a/test/test_accumulator.jl b/test/test_accumulator.jl
index 119efac..861052d 100644
--- a/test/test_accumulator.jl
+++ b/test/test_accumulator.jl
@@ -90,6 +90,16 @@
         @test ctm["b"] == 0
     end
 
+    @testset "From AbstractDict" begin
+        kv = (:a => 1, :b => 2)
+        for f in (Accumulator, counter)
+            ct_odict = f(OrderedDict(kv))
+            ct_dict = f(Dict(kv))
+            @test ct_odict isa Accumulator{Symbol, Int}
+            @test ct_odict == ct_dict
+        end
+    end
+
     @testset "From Pair" begin
         ct4 = counter(Pair{Int,Int})
         @test isa(ct4, Accumulator{Pair{Int,Int}})