diff --git a/docs/REPLICA_SETS.md b/docs/REPLICA_SETS.md
index 4b26a0b..5722676 100644
--- a/docs/REPLICA_SETS.md
+++ b/docs/REPLICA_SETS.md
@@ -6,17 +6,17 @@ Here follow a few considerations for those using the MongoDB Ruby driver with [r
 
 First, make sure that you've configured and initialized a replica set.
 
-Use `Connection.multi` to connect to a replica set:
+Use `ReplSetConnection.new` to connect to a replica set:
 
-    @connection = Connection.multi([['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017]])
+    @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017])
 
 The driver will attempt to connect to a master node and, when found, will replace all seed nodes with known members of the replica set.
 
 ### Read slaves
 
-If you want to read from a seconday node, you can pass :read_secondary => true to Connection#multi.
+If you want to read from a seconday node, you can pass :read_secondary => true to ReplSetConnection#new.
 
-    @connection = Connection.multi([['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017]],
+    @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017],
                   :read_secondary => true)
 
 A random secondary will be chosen to be read from. In a typical multi-process Ruby application, you'll have a good distribution of reads across secondary nodes.
@@ -62,14 +62,12 @@ Of course, the proper way to handle connection failures will always depend on th
 
 ### Testing
 
-The Ruby driver (>= 1.0.6) includes some unit tests for verifying replica set behavior. They reside in *tests/replica_sets*. You can run them individually with the following rake tasks:
+The Ruby driver (>= 1.1.5) includes unit tests for verifying replica set behavior. They reside in *tests/replica_sets*. You can run them as a group with the following rake task:
 
-    rake test:replica_set_count
-    rake test:replica_set_insert
-    rake test:pooled_replica_set_insert
-    rake test:replica_set_query
+    rake test:rs
 
-Make sure you have a replica set running on localhost before trying to run these tests.
+The suite will set up a five-node replica set by itself and ensure that driver behaves correctly even in the face
+of individual node failures. Node that the `mongod` executable must be in the search path for this to work.
 
 ### Further Reading
 
diff --git a/lib/mongo/repl_set_connection.rb b/lib/mongo/repl_set_connection.rb
index 99088fb..f90d593 100644
--- a/lib/mongo/repl_set_connection.rb
+++ b/lib/mongo/repl_set_connection.rb
@@ -18,10 +18,44 @@
 
 module Mongo
 
-  # Instantiates and manages connections to MongoDB.
+  # Instantiates and manages connections to a MongoDB replica set.
   class ReplSetConnection < Connection
     attr_reader :nodes, :secondaries, :arbiters, :read_pool, :secondary_pools
 
+    # Create a connection to a MongoDB replica set.
+    #
+    # Once connected to a replica set, you can find out which nodes are primary, secondary, and
+    # arbiters with the corresponding accessors: Connection#primary, Connection#secondaries, and
+    # Connection#arbiters. This is useful if your application needs to connect manually to nodes other
+    # than the primary.
+    #
+    # @param [Array] args A list of host-port pairs ending with a hash containing any options. See
+    #   the examples below for exactly how to use the constructor.
+    #
+    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    #   propogated to DB objects instantiated off of this Connection. This
+    #   default can be overridden upon instantiation of any DB by explicity setting a :safe value
+    #   on initialization.
+    # @option options [Boolean] :read_secondary(false) If true, a random secondary node will be chosen,
+    #   and all reads will be directed to that node.
+    # @option options [Logger, #debug] :logger (nil) Logger instance to receive driver operation log.
+    # @option options [Integer] :pool_size (1) The maximum number of socket connections allowed per
+    #   connection pool. Note: this setting is relevant only for multi-threaded applications.
+    # @option options [Float] :timeout (5.0) When all of the connections a pool are checked out,
+    #   this is the number of seconds to wait for a new connection to be released before throwing an exception.
+    #   Note: this setting is relevant only for multi-threaded applications.
+    #
+    # @example Connect to a replica set and provide two seed nodes:
+    #   ReplSetConnection.new(['localhost', 30000], ['localhost', 30001])
+    #
+    # @example Connect to a replica set providing two seed nodes and allowing reads from a
+    #   secondary node:
+    #   ReplSetConnection.new(['localhost', 30000], ['localhost', 30001], :read_secondary => true)
+    #
+    # @see http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html Replica sets in Ruby
+    #
+    # @raise [ReplicaSetConnectionError] This is raised if a replica set name is specified and the
+    #   driver fails to connect to a replica set with that name.
     def initialize(*args)
       if args.last.is_a?(Hash)
         opts = args.pop