Improve docstrings and doc

[s-celles]

Hello,

Doc need now to be improved

Example:
http://juliacollections.github.io/DataStructures.jl/latest/deque.html
(but it also apply to most doc page)

Instead of a usage paragraph with raw Julia code we should use docstrings and @docs

Example of docstring for isempty
https://github.com/JuliaLang/julia/blob/edeb002a13afdce31dac55706433ebb6d5cedd79/base/essentials.jl#L727

Writing doc this way will help to have a doc which really reflect current code (and avoid issues with documentation of constructors such as exposed in #340 )

Maybe a new release should be tagged before tackling this issue because it will be easier to compare latest version (with @docs) to previous (current) version with raw Julia code in doc.

Kind regards

[oxinabox]

I'ld suggest putting this on the backburner until #310.
Than after that is done there will be 5 packages and one can go through and tackle them one at a time.

[s-celles]

I noticed that one reason for splitting this package is that it should help fixing (future) dep warning. Is https://github.com/apps/femtocleaner installed ?

[s-celles]

When trying to build doc, we get:

!! No docs found for 'find(m::SortedDict, k_)'. [src/sorted_containers.md]
!! No docs found for 'get(sd::SortedDict,k,v)'. [src/sorted_containers.md]
!! No docs found for 'get!(sd::SortedDict,k,v)'. [src/sorted_containers.md]

Maybe @mortenpi @fredrikekre or @KristofferC who are active contributor of Documenter.jl can tell us why we are facing this

[mortenpi]

As far as I can tell, DataStructures does not define find(m::SortedDict, k_) at all. As for get and get!: the docstrings appear to be attached to a different signature, e.g. get(default_::Union{Function,Type}, m::SortedDict{K,D}, k_) where {K,D}, not get(m::SortedDict, k_, default_).

[s-celles]

Thanks @mortenpi
Sorry for noise.

[s-celles]

Doc should explain:

• how to install and use this package (latest tagged version)
• how to install development version and run all unit tests (or run just one test file)
• how to contribute to this repository (both technically and code of conduct)

[s-celles]

https://travis-ci.org/JuliaCollections/DataStructures.jl/jobs/413204515#L836 shows 89 potentially missing docstrings

https://travis-ci.org/JuliaCollections/DataStructures.jl/jobs/413204515#L820 shows expanding markdown templates that are failing because no docs is found

[s-celles]

using @repl code block (and @setup) https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@repl-block-1
could help to have examples reflecting exactly current state of DataStructures code.

[s-celles]

Anyone here have ever used https://juliadocs.github.io/DocStringExtensions.jl/latest/ and $(SIGNATURES) https://juliadocs.github.io/DocStringExtensions.jl/latest/index.html#DocStringExtensions.SIGNATURES ?