RUBY-295 document tailable cursor API.

README.md

@@ -7,12 +7,13 @@ 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. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html).
-5. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html).
-6. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html).
-7. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
-8. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html).
-9. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html).
+4. [Tailable Cursors in Ruby](http://api.mongodb.org/ruby/current/file.TAILABLE_CURSORS.html).
+5. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html).
+6. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html).
+7. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html).
+8. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
+9. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html).
+10. [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:

docs/TAILABLE_CURSORS.md

@@ -0,0 +1,51 @@
+# Tailable in Ruby
+
+Tailable cursors are cursors that remain open even after they've returned
+a final result. This way, if more documents are added to a collection (i.e.,
+to the cursor's result set), then you can continue to call `Cursor#next` to
+retrieve those results. Here's a complete test case that demonstrates the use
+of tailable cursors.
+
+Note that tailable cursors are for capped collections only.
+
+      require 'mongo'
+      require 'test/unit'
+
+      class TestTailable < Test::Unit::TestCase
+        include Mongo
+
+        def test_tailable
+
+          # Create a connection and capped collection.
+          @con = Connection.new
+          @db  = @con['test']
+          @db.drop_collection('log')
+          @capped = @db.create_collection('log', :capped => true, :size => 1024)
+
+          # Insert 10 documents.
+          10.times do |n|
+            @capped.insert({:n => n})
+          end
+
+          # Create a tailable cursor that iterates the collection in natural order
+          @tail = Cursor.new(@capped, :tailable => true, :order => [['$natural', 1]])
+
+          # Call Cursor#next 10 times. Each call returns a document.
+          10.times do
+            assert @tail.next
+          end
+
+          # But the 11th time, the cursor returns nothing.
+          assert_nil @tail.next
+
+          # Add a document to the capped collection.
+          @capped.insert({:n => 100})
+
+          # Now call Cursor#next again. This will return the just-inserted result.
+          assert @tail.next
+
+          # Close the cursor.
+          @tail.close
+        end
+
+      end