Ensure docs follow the standard format

[sjspielman]

Counterpoint: It turns out this is a great demonstration of "people may miss docs if they have to scroll past arguments".

I want to note that I'm conflicted here! I very much take the point that the docs are there, I just missed them, but how meaningful is it that I missed them is the question I'm not sure of...

I think my general thought is that we should probably follow the standard format more closely. If the expected documentation standard is that descriptions should be a short paragraph, we should do that, and put the rest in the details section. I don't think that the usage of this package deviates in any significant way from any other package that would justify doing things much differently.

That may mean some reformatting, and I am not wholly opposed to adding @description and @details; I just don't think we need to do it everywhere as you have done here. (And I would keep them on their own lines for aesthetics.)

I was also partly confused by your initial description of the problem, where you talked about line breaks, but what you meant was paragraph breaks (blank lines).

Originally posted by @jashapiro in #26 (comment)

---

This issue was opened in lieu of #26 to update the docs, where needed, to ensure they follow a standard format as described.