Improve docstrings and doc

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

Start with the deque documentation page linked in the issue and compare its raw Julia usage paragraphs with Julia docstrings and @docs, using the linked isempty example as a reference. Identify the affected documentation pages and convert their examples to reflect the current code; done means the relevant pages consistently use docstrings and @docs rather than duplicated raw usage text.