Provide more information in API docstrings

[flpa]

In my opinion, documentation of API methods should be extended so that it's easier to use them without looking up their source or experimenting.

For example, get-subreddit-new is described with "Gets json data for /r/< sub>/new. Optional user."
I think it'd be helpful to mention that the function returns a list of link objects.

[jperson]

I agree, the documentation is pretty minimal.