DOC: Corrected documentation for return types.

Added an example in the examples section as well. Closes #3740