RUBY-284 RUBY-291 document read preference with secondary ping time

README.md

@@ -7,11 +7,12 @@ This documentation includes other articles of interest, include:
 1. [A tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html).
 2. [Replica Sets in Ruby](http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html).
 3. [Write Concern in Ruby](http://api.mongodb.org/ruby/current/file.WRITE_CONCERN.html).
-4. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html).
+4. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html).
-5. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html).
+5. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html).
-6. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
+6. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html).
-6. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html).
+7. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
-7. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html).
+8. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html).
+9. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html).
 
 Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html)
 for much more:

Rakefile

@@ -141,7 +141,7 @@ task :ydoc do
   require File.join(File.dirname(__FILE__), 'lib', 'mongo')
   out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
-  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md"
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e ./yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/READ_PREFERENCE.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md"
 end
 
 namespace :bamboo do

docs/READ_PREFERENCE.md

@@ -0,0 +1,39 @@
+# Read Preference in Ruby
+
+## Setting the read preference
+
+You can using the `:read` option to specify a query's read preference. There are for now two possible options:
+
+    @collection.find({:doc => 'foo'}, :read => :primary)
+    @collection.find({:doc => 'foo'}, :read => :secondary)
+
+In the first case, the query will be directed to the primary node in a replica set. In the second, the query will be sent
+to a secondary node. The driver will attempt to choose a secondary node that's nearby, as determined by ping time. If more
+than one secondary node is closeby (e.g, responds to pings within 10ms), then a random node within this subset will be chosen.
+
+## Read preference inheritance
+
+The Ruby driver allows you to set read preference on each of four levels: the connection, database, collection, and cursor (or read operation).
+Objects will inherit the default read preference from their parents. Thus, if you set a read preference of `{:read => :secondary}` when creating
+a new connection, then all databases and collections created from that connection will inherit the same setting. See this code example:
+
+    @con = Mongo::ReplSetConnection.new([['localhost', 27017], ['localhost', 27018]], :read => :secondary)
+    @db  = @con['test']
+    @collection = @db['foo']
+    @collection.find({:name => 'foo'})
+
+    @collection.find({:name => 'bar'}, :read => :primary)
+
+Here, the first call to Collection#find will use the inherited read preference, `{:read => :secondary}`. But the second call
+to Collection#find overrides this setting by setting the preference to `:primary`.
+
+You can examine the read preference on any object by calling its `read_preference` method:
+
+    @con.read_preference
+    @db.read_preference
+    @collection.read_preference
+
+## Future work
+
+In the v2.0 release of the driver, you'll also be able to specify a read preference consisting of a set of tags. This way,
+you'll be able to direct reads to a replica set member. You can follow this issue's progress here: (https://jira.mongodb.org/browse/RUBY-326).