Update docstrings to new conventions

[nalimilan]

We should improve our docstrings by adapting them to new conventions from the Julia manual. In particular (not all of these steps need to be done at the same time, though):

• [x] stop using @doc and -> (except for special cases)
• [x] give the signature with a four-space indent (instead of backquotes)
• [ ] use imperative form ("return") instead of third person ("returns")
• [ ] remove docstrings for generic functions which do not really add NullableArray-specific information (like unshift!, shift!, pop!, splice!, etc.)
• [ ] add examples as doctests where useful

[nalimilan]

Points 1 and 2 have been addressed by https://github.com/JuliaStats/NullableArrays.jl/pull/162 (thanks, @RatanRSur!).

[ararslan]

I hope you don't mind but I converted your list to a checklist for easier tracking of what's been done.