tidy up posix_getopts documentation
Currently the documentation is all over the place and rather redundant, as I had no idea how it should be distributed between the module, the classes, and the functions. Now that I have a better understanding how this should work, I should be able to improve it. Further study of the Python documentation conventions may be advisable.