Add Return information to docstring.

[erewok]

Docstring now doesn't contain a returns: section, which would make it a little more official.

Ideally, we'd include more information about the types of things that go into the functions as arguments, including the data payload, etc. That may involve more knowledge about Python than this library currently pretends to.

In addition, we should be able to include some information in the returns section about the kind of object likely to get returned.

[erewok]

Use Data.Typeable for this?

Prelude> import Data.Typeable
Prelude Data.Typeable> show $ typeOf 5
"Integer"
Prelude Data.Typeable> show $ typeOf (5 :: Int)
"Int"

One thing that may be useful is to define a version of the Options type that includes more information about request bodies and also about objects returned, which we could put into the docstrings to help users.

The thing is, the objects going into and getting returned from APIs would need to derive Data and Typeable for this to work, so it could be fiddly and confusing why a particular options parameter makes things suddenly start breaking.

Inspiration for using Typeable and Data can be seen here:

• http://stackoverflow.com/questions/8457876/get-a-haskell-records-field-names-as-a-list-of-strings
• http://chrisdone.com/posts/data-typeable