minor: docs

README.rdoc

@@ -25,7 +25,6 @@ The driver's gems are hosted on Gemcutter[http://gemcutter.org]. If you haven't
 installed a gem from Gemcutter before, you'll need to set up Gemcutter first:
 
   $ gem install gemcutter
-  $ gem tumble
 
 Once you've installed Gemcutter, install the mongo gem as follows:
 
@@ -104,7 +103,7 @@ Examples:
 
   # Write a file on disk to the Grid
   file = File.open('image.jpg')
-  grid = GridFileSystem.new(db)
+  grid = Grid.new(db)
   id   = grid.put(file)
 
   # Retrieve the file

lib/mongo/connection.rb

@@ -188,7 +188,8 @@ module Mongo
 
     # Save an authentication to this connection. When connecting,
     # the connection will attempt to re-authenticate on every db
-    # specificed in the list of auths.
+    # specificed in the list of auths. This method is called automatically
+    # by DB#authenticate.
     #
     # @param [String] db_name
     # @param [String] username

lib/mongo/db.rb

@@ -76,13 +76,16 @@ module Mongo
     #
     # @param [String] username
     # @param [String] password
+    # @param [Boolean] save_auth
+    #   Save this authentication to the connection object using Connection#add_auth. This
+    #   will ensure that the authentication will be applied on database reconnect.
     #
     # @return [Boolean]
     #
     # @raise [AuthenticationError]
     #
     # @core authenticate authenticate-instance_method
-    def authenticate(username, password, save_authorization=true)
+    def authenticate(username, password, save_auth=true)
       doc = command(:getnonce => 1)
       raise "error retrieving nonce: #{doc}" unless ok?(doc)
       nonce = doc['nonce']

lib/mongo/gridfs.rb

@@ -15,11 +15,15 @@
 # ++
 require 'mongo/gridfs/grid_store'
 
+# DEPRECATED. Plese see GridFileSystem and Grid classes.
+#
 # GridFS is a specification for storing large binary objects in MongoDB.
 # See the documentation for GridFS::GridStore
 #
 # @see GridFS::GridStore
 #
 # @core gridfs
+#
+# @deprecated
 module GridFS
 end

lib/mongo/gridfs/grid.rb

@@ -24,6 +24,7 @@ module Mongo
     # and a filesystem prefix if not using the default.
     #
     # @core gridfs
+    #
     # @see GridFileSystem
     def initialize(db, fs_name=DEFAULT_FS_NAME)
       raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB)
@@ -41,6 +42,16 @@ module Mongo
     # @param [String, #read] data a string or io-like object to store.
     # @param [String] filename a name for the file.
     #
+    # @options opts [Hash] :metadata ({}) any additional data to store with the file.
+    # @options opts [ObjectID] :_id (ObjectID) a unique id for
+    #   the file to be use in lieu of an automatically generated one.
+    # @options opts [String] :content_type ('binary/octet-stream') If no content type is specified,
+    #   the content type will may be inferred from the filename extension if the mime-types gem can be
+    #   loaded. Otherwise, the content type 'binary/octet-stream' will be used.
+    # @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
+    # @options opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
+    #   will be validated using an md5 hash. If validation fails, an exception will be raised.
+    #
     # @return [Mongo::ObjectID] the file's id.
     def put(data, filename, opts={})
       opts.merge!(default_grid_io_opts)

lib/mongo/gridfs/grid_file_system.rb

@@ -38,11 +38,23 @@ module Mongo
       @default_query_opts = {:sort => [['filename', 1], ['uploadDate', -1]], :limit => 1}
     end
 
-    # Open a file for reading or writing.
+    # Open a file for reading or writing. Note that the options for this method only apply
+    # when opening in 'w' mode.
     #
     # @param [String] filename the name of the file.
     # @param [String] mode either 'r' or 'w' for reading from
     #   or writing to the file.
+    # @param [Hash] opts see GridIO#new
+    #
+    # @options opts [Hash] :metadata ({}) any additional data to store with the file.
+    # @options opts [ObjectID] :_id (ObjectID) a unique id for
+    #   the file to be use in lieu of an automatically generated one.
+    # @options opts [String] :content_type ('binary/octet-stream') If no content type is specified,
+    #   the content type will may be inferred from the filename extension if the mime-types gem can be
+    #   loaded. Otherwise, the content type 'binary/octet-stream' will be used.
+    # @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
+    # @options opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
+    #   will be validated using an md5 hash. If validation fails, an exception will be raised.
     #
     # @example
     #