Fixes #152.

Add tests for RateLimitError.

Refactor populateRate into a more general parseRate.

Rate is now a method, not a field.

Mention RateLimits rather than RateLimit since the latter is deprecated.

Use Go convention for marking deprecated identifiers. See
257114af91.

First draft, suggestions for improvements are welcome. The snippet
should serve as the idiomatic guide on how to get all pages for a given
resource (a common use case without an obvious solution, hence the docs
can be very helpful).

- minor updates to README
- expand package docs to include more information on authentication, as
  well as new sections for rate limiting and setting pointer values.

our package docs are too long yet to really need to be in their own
file, but I'd like to flesh them out a bit more, particularly once #19
is resolved.