Major Docs Patch

Am baby sitting my aunt.. so using time to make revel docs better..

here's first patch, but going thru and tweaking bits and pieces..

I kind want to push to the "upstream"  origin and have perms, but am nervous to do so.. (maybe into a new "docs_next" branch)


punctuation: ", which contain routes, can be"