Update and unwrap README, move function docs in-line
    
    The README looks pretty ugly on Pagure. So let's unwrap it.
    Let's also move the function docs into the source files. We're
    much more likely to keep them up to date that way, I think. We
    should probably change over to proper perl POD documentation at
    some point, but comments in-line are OK for now I think.