Add @returns and @examples to documentation

[gowerc]

The current package is largely devoid of any @returns or @examples in the documentation. This is likely to be a problem if we were ever to proceed with a CRAN submission and would need to be addressed.