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):

• stop using @doc and -> (except for special cases)
• 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 #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.