doc: full API

[ivanoblomov]

Closes: #201

Goal

Document the full API including attributes and aliases.

Approach

1. Force RDoc to document metaprogrammed attribute-readers with:

     # :attr_reader: city

2. Add @return types to aliases to satisfy inch --pedantic.
3. Add @return, @example to #coordinates.
4. Describe attribute and their aliases consistently.
5. Move variable types before names for consistency.
6. (Fully qualify require path in README.)

Signed-off-by: Roderick Monje rod@foveacentral.com

[ivanoblomov]

@olleolleolle any way you can review this and #145 when you get a chance?

Thanks in advance!