Fixed and enhanced function documentation.

[dwmuller]

I fixed the markdown formatting, made the function headings a little more descriptive by adding arguments to them, and made a variety of other small improvements to the text in README.md.