Merge pull request alexreisner#1112 from jmccartie/patch-1

Update README.md

README.md

@@ -1,9 +1,9 @@
 Geocoder
 ========
 
-Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding (by street or IP address), reverse geocoding (finding street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`.
+Geocoder is a complete geocoding solution for Ruby. With Rails, it adds geocoding (by street or IP address), reverse geocoding (finding street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`.
 
-_Please note that this README is for the current `HEAD` and may document features not present in the latest gem release. For this reason, you may want to instead view the README for your particular version._
+_Please note that this README is for the current `HEAD` and may document features not present in the latest gem release. For this reason, you may want to instead view the README for your [particular version](https://github.com/alexreisner/geocoder/releases)._
 
 
 Compatibility
@@ -47,7 +47,7 @@ Your model must have two attributes (database columns) for storing latitude and
     rails generate migration AddLatitudeAndLongitudeToModel latitude:float longitude:float
     rake db:migrate
 
-For geocoding your model must provide a method that returns an address. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: `city`, `state`, and `country`).
+For geocoding, your model must provide a method that returns an address. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: `city`, `state`, and `country`).
 
 Next, your model must tell Geocoder which method returns your object's geocodable address:
 
@@ -102,7 +102,7 @@ By default, the methods `geocoded_by` and `reverse_geocoded_by` create a geospat
 
 ### Bulk Geocoding
 
-If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all:
+If you have just added geocoding to an existing application with a lot of objects, you can use this Rake task to geocode them all:
 
     rake geocode:all CLASS=YourModel
 
@@ -244,16 +244,16 @@ If your model has `street`, `city`, `state`, and `country` attributes you might
       [street, city, state, country].compact.join(', ')
     end
 
-For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example:
+For reverse geocoding, you can also specify an alternate name attribute where the address will be stored. For example:
 
     reverse_geocoded_by :latitude, :longitude, :address => :location  # ActiveRecord
     reverse_geocoded_by :coordinates, :address => :loc                # MongoDB
 
-You can also configure a specific lookup for your model which will override the globally-configured lookup, for example:
+You can also configure a specific lookup for your model which will override the globally-configured lookup. For example:
 
     geocoded_by :address, :lookup => :yandex
 
-You can also specify a proc if you want to choose a lookup based on a specific property of an object, for example you can use specialized lookups for different regions:
+You can also specify a proc if you want to choose a lookup based on a specific property of an object. For example, you can use specialized lookups for different regions:
 
     geocoded_by :address, :lookup => lambda{ |obj| obj.geocoder_lookup }
 
@@ -278,7 +278,7 @@ When querying for objects (if you're using ActiveRecord) you can also look withi
     box = Geocoder::Calculations.bounding_box(center_point, distance)
     Venue.within_bounding_box(box)
 
-This can also dramatically improve query performance, especially when used in conjunction with indexes on the latitude/longitude columns. Note, however, that returned results do not include `distance` and `bearing` attributes. Note that `#near` performs both bounding box and radius queries for speed.
+This can also dramatically improve query performance, especially when used in conjunction with indexes on the latitude/longitude columns. Note, however, that returned results do not include `distance` and `bearing` attributes. Also note that `#near` performs both bounding box and radius queries for speed.
 
 You can also specify a minimum radius (if you're using ActiveRecord and not Sqlite) to constrain the
 lower bound (ie. think of a donut, or ring) by using the `:min_radius` option:
@@ -293,7 +293,7 @@ With ActiveRecord, you can specify alternate latitude and longitude column names
 Advanced Geocoding
 ------------------
 
-So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of `Geocoder::Result` objects) in which you handle the parsed geocoding result any way you like, for example:
+So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy, you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of `Geocoder::Result` objects) in which you handle the parsed geocoding result any way you like, for example:
 
     reverse_geocoded_by :latitude, :longitude do |obj,results|
       if geo = results.first
@@ -355,7 +355,7 @@ Some common configuration options are:
 
     )
 
-Please see lib/geocoder/configuration.rb for a complete list of configuration options. Additionally, some lookups have their own configuration options, some of which are directly supported by Geocoder. For example, to specify a value for Google's `bounds` parameter:
+Please see `lib/geocoder/configuration.rb` for a complete list of configuration options. Additionally, some lookups have their own configuration options, some of which are directly supported by Geocoder. For example, to specify a value for Google's `bounds` parameter:
 
     # with Google:
     Geocoder.search("Paris", :bounds => [[32.1,-95.9], [33.9,-94.3]])
@@ -392,7 +392,7 @@ You can also configure multiple geocoding services at once, like this:
 
     )
 
-The above combines global and service-specific options and could be useful if you specify different geocoding services for different models or under different conditions. Lookup-specific settings override global settings so, for example, in the above the timeout for all lookups would be 2 seconds, except for Yandex which would be 5.
+The above combines global and service-specific options and could be useful if you specify different geocoding services for different models or under different conditions. Lookup-specific settings override global settings. In the above example, the timeout for all lookups would be 2 seconds, except for Yandex which would be 5.
 
 
 ### Street Address Services
@@ -859,7 +859,7 @@ You must add either the *[hive_geoip2](https://rubygems.org/gems/hive_geoip2)* g
 Caching
 -------
 
-It's a good idea, when relying on any external service, to cache retrieved data. When implemented correctly it improves your app's response time and stability. It's easy to cache geocoding results with Geocoder, just configure a cache store:
+When relying on any external service, it's always a good idea to cache retrieved data. When implemented correctly, it improves your app's response time and stability. It's easy to cache geocoding results with Geocoder -- just configure a cache store:
 
     Geocoder.configure(:cache => Redis.new)
 
@@ -886,17 +886,17 @@ If you need to expire cached content:
     # Be aware that this methods spawns a new Lookup object for each Service
     Geocoder::Lookup.all_services.each{|service| Geocoder::Lookup.get(service).cache.expire(:all)}
 
-Do *not* include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix (won't kill every entry in your key/value store).
+Do *not* include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix -- it will *not* expire every entry in your key/value store.
 
-For an example of a cache store with URL expiry please see examples/autoexpire_cache.rb
+For an example of a cache store with URL expiry, please see examples/autoexpire_cache.rb
 
 _Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your geocoding service._
 
 
 Forward and Reverse Geocoding in the Same Model
 -----------------------------------------------
 
-If you apply both forward and reverse geocoding functionality to the same model (say users can supply an address or coordinates and you want to fill in whatever's missing), you will provide two address methods:
+If you apply both forward and reverse geocoding functionality to the same model (i.e. users can supply an address or coordinates and you want to fill in whatever's missing), you will provide two address methods:
 
 * one for storing the fetched address (reverse geocoding)
 * one for providing an address to use when fetching coordinates (forward geocoding)
@@ -923,7 +923,7 @@ However, there can be only one set of latitude/longitude attributes, and whichev
       reverse_geocoded_by :latitude, :longitude
     end
 
-The reason for this is that we don't want ambiguity when doing distance calculations. We need a single, authoritative source for coordinates!
+We don't want ambiguity when doing distance calculations -- we need a single, authoritative source for coordinates!
 
 Once both forward and reverse geocoding has been applied, it is possible to call them sequentially.
 
@@ -935,7 +935,7 @@ For example:
 
     end
 
-For certain geolocation services such as Google geolocation API this may cause issues during subsequent updates to database records if the longitude and latitude coordinates cannot be associated known location address (on a large body of water for example). On subsequent callbacks the following call:
+For certain geolocation services such as Google's geolocation API, this may cause issues during subsequent updates to database records if the longitude and latitude coordinates cannot be associated with a known location address (on a large body of water for example). On subsequent callbacks the following call:
 
      after_validation :geocode
 
@@ -1053,16 +1053,16 @@ For consistency with the rest of Geocoder, always use the `to_coordinates` metho
 Notes on Non-Rails Frameworks
 -----------------------------
 
-If you are using Geocoder with ActiveRecord and a framework other than Rails (like Sinatra or Padrino) you will need to add this in your model before calling Geocoder methods:
+If you are using Geocoder with ActiveRecord and a framework other than Rails (like Sinatra or Padrino), you will need to add this in your model before calling Geocoder methods:
 
     extend Geocoder::Model::ActiveRecord
 
 Optimisation of Distance Queries
 --------------------------------
 
-In MySQL and Postgres the finding of objects near a given point is speeded up by using a bounding box to limit the number of points over which a full distance calculation needs to be done.
+In MySQL and Postgres, the finding of objects near a given point is sped up by using a bounding box to limit the number of points over which a full distance calculation needs to be done.
 
-To take advantage of this optimisation you need to add a composite index on latitude and longitude. In your Rails migration:
+To take advantage of this optimisation, you need to add a composite index on latitude and longitude. In your Rails migration:
 
     add_index :table, [:latitude, :longitude]