DOC: Corrected documentation for return types.

Added an example in the examples section as well. Closes #3740
Merge pull request #3938 from venthur/fix-3740

DOC: Corrected documentation for return types.