Documentation

[rrydbirk]

Documentation needs to be complete.

• [x] All arguments needs an explanation and (default = X)

• [x] We need to define @return and write @examples

• [x] We need to state whether inner functions are @internal or will be @export

[flkick]

Arguments added in 277588c

[flkick]

Return and examples added in 8866907