Documentation improvements: cleanups and add return type information

Closes #2147