From 8e026ebb11d498e04be86d461835a4d09cf41137 Mon Sep 17 00:00:00 2001
From: Jim Menard <jim@10gen.com>
Date: Thu, 29 Jan 2009 11:31:45 -0500
Subject: [PATCH] documentation

---
 README.rdoc                    | 51 ++++++++++++++++++++++++++++++++++
 lib/mongo/gridfs/grid_store.rb |  3 +-
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/README.rdoc b/README.rdoc
index d4c6985..30fcc35 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -61,12 +61,49 @@ See also the test code, especially tests/test_db_api.rb.
 For the GridFS class GridStore, see the tests.
 
 
+= The Driver
+
+Here is some simple example code:
+
+  require 'rubygems'        # not required for Ruby 1.9
+  require 'mongo'
+
+  include XGen::Mongo::Driver
+  db = Mongo.new.db('my-db-name')
+  things = db.collection('things')
+
+  things.clear
+  things.insert('a' => 42)
+  things.insert('a' => 99, 'b' => Time.now)
+  puts things.count                               # => 2
+  puts things.find('a' => 42).next_object.inspect # {"a"=>42}
+
+
 = GridStore
 
 The GridStore class is a Ruby implementation of Mongo's GridFS file storage
 system. An instance of GridStore is like an IO object. See the rdocs for
 details.
 
+Note that the GridStore class is not automatically required when you require
+'mongo'. You need to require 'mongo/gridfs'.
+
+Example code:
+
+  GridStore.open(database, 'filename', 'w') { |f|
+    f.puts "Hello, world!"
+  }
+  GridStore.open(database, 'filename, 'r') { |f|
+    puts f.read         # => Hello, world!\n
+  }
+  GridStore.open(database, 'filename', 'w+') { |f|
+    f.puts "But wait, there's more!"
+  }
+  GridStore.open(database, 'filename, 'r') { |f|
+    puts f.read         # => Hello, world!\nBut wait, there's more!\n
+  }
+
+
 
 = Notes
 
@@ -112,6 +149,20 @@ Here is a sample primary key factory, taken from the tests:
     end
   end
 
+Here's a slightly more sophisticated one that handles both symbol and string
+keys. This is the PKFactory that comes with the MongoRecord code (an
+ActiveRecord-like framework for non-Rails apps) and the AR Mongo adapter code
+(for Rails):
+
+  class PKFactory
+    def create_pk(row)
+      return row if row[:_id]
+      row.delete(:_id)      # in case it exists but the value is nil
+      row['_id'] ||= XGen::Mongo::Driver::ObjectID.new
+      row
+    end
+  end
+
 A database's PK factory object may be set after you obtain it, but only once.
 The only reason it is changeable is so that libraries such as MongoRecord that
 use this driver can set the PK factory after obtaining the database but before
diff --git a/lib/mongo/gridfs/grid_store.rb b/lib/mongo/gridfs/grid_store.rb
index a76f2ce..3035c1e 100644
--- a/lib/mongo/gridfs/grid_store.rb
+++ b/lib/mongo/gridfs/grid_store.rb
@@ -13,13 +13,14 @@ module XGen
       #
       # Example code:
       #
+      #   require 'mongo/gridfs'
       #   GridStore.open(database, 'filename', 'w') { |f|
       #     f.puts "Hello, world!"
       #   }
       #   GridStore.open(database, 'filename, 'r') { |f|
       #     puts f.read         # => Hello, world!\n
       #   }
-      #   GridStore.open(database, 'filename', 'w+") { |f|
+      #   GridStore.open(database, 'filename', 'w+') { |f|
       #     f.puts "But wait, there's more!"
       #   }
       #   GridStore.open(database, 'filename, 'r') { |f|