GridFS docs

lib/mongo/gridfs/grid.rb

@@ -16,10 +16,15 @@
 
 module Mongo
 
-  # WARNING: This class is part of a new, experimental GridFS API. Subject to change.
+  # Implements the basic MongoDB GridFS specification.
   class Grid
     DEFAULT_FS_NAME = 'fs'
 
+    # Initialize a new Grid instance, consisting of a MongoDB database
+    # 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)
 
@@ -31,6 +36,12 @@ module Mongo
       @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]])
     end
 
+    # Store a file in the file store.
+    #
+    # @param [String, #read] data a string or io-like object to store.
+    # @param [String] filename a name for the file.
+    #
+    # @return [Mongo::ObjectID] the file's id.
     def put(data, filename, opts={})
       opts.merge!(default_grid_io_opts)
       file = GridIO.new(@files, @chunks, filename, 'w', opts=opts)
@@ -39,11 +50,21 @@ module Mongo
       file.files_id
     end
 
+    # Read a file from the file store.
+    #
+    # @param [] id the file's unique id.
+    #
+    # @return [Mongo::GridIO]
     def get(id)
       opts = {:query => {'_id' => id}}.merge!(default_grid_io_opts)
       GridIO.new(@files, @chunks, nil, 'r', opts)
     end
 
+    # Delete a file from the store.
+    #
+    # @param [] id
+    #
+    # @return [Boolean]
     def delete(id)
       @files.remove({"_id" => id})
       @chunks.remove({"_id" => id})

lib/mongo/gridfs/grid_file_system.rb

@@ -16,9 +16,16 @@
 
 module Mongo
 
-  # WARNING: This class is part of a new, experimental GridFS API. Subject to change.
+  # A file store built on the GridFS specification featuring
+  # an API and behavior similar to that of a traditional file system.
   class GridFileSystem < Grid
 
+    # Initialize a new Grid instance, consisting of a MongoDB database
+    # and a filesystem prefix if not using the default.
+    #
+    # @param [Mongo::DB] db a MongoDB database.
+    # @param [String] fs_name A name for the file system. The default name, based on
+    #   the specification, is 'fs'.
     def initialize(db, fs_name=Grid::DEFAULT_FS_NAME)
       raise MongoArgumentError, "db must be a Mongo::DB." unless db.is_a?(Mongo::DB)
 
@@ -31,6 +38,32 @@ module Mongo
       @default_query_opts = {:sort => [['filename', 1], ['uploadDate', -1]], :limit => 1}
     end
 
+    # Open a file for reading or writing.
+    #
+    # @param [String] filename the name of the file.
+    # @param [String] mode either 'r' or 'w' for reading from
+    #   or writing to the file.
+    #
+    # @example
+    #
+    #  # Store the text "Hello, world!" in the grid file system.
+    #  @grid = GridFileSystem.new(@db)
+    #  @grid.open('filename', 'w') do |f|
+    #    f.write "Hello, world!"
+    #  end
+    #
+    #  # Output "Hello, world!"
+    #  @grid = GridFileSystem.new(@db)
+    #  @grid.open('filename', 'r') do |f|
+    #    puts f.read
+    #  end
+    #
+    #  # Write a file on disk to the GridFileSystem
+    #  @file = File.open('image.jpg')
+    #  @grid = GridFileSystem.new(@db)
+    #  @grid.open('image.jpg, 'w') do |f|
+    #    f.write @file
+    #  end
     def open(filename, mode, opts={})
       opts.merge!(default_grid_io_opts(filename))
       file   = GridIO.new(@files, @chunks, filename, mode, opts)
@@ -44,6 +77,12 @@ module Mongo
       result
     end
 
+    # Delete the file with the given filename. Note that this will delete
+    # all versions of the file.
+    #
+    # @param [String] filename
+    #
+    # @return [Boolean]
     def delete(filename)
       files = @files.find({'filename' => filename}, :fields => ['_id'])
       files.each do |file|

lib/mongo/gridfs/grid_io.rb

@@ -37,7 +37,16 @@ module Mongo
     #
     # @option opts [Hash] :query a query selector used when opening the file in 'r' mode.
     # @option opts [Hash] :query_opts any query options to be used when opening the file in 'r' mode.
-    # @option opts [String] :fs_name the file system prefix. Defaults to 'fs'
+    # @option opts [String] :fs_name the file system prefix.
+    # @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
+    # @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 be inferred from the filename extension. If that can't be done, the default
+    #   content type of 'binary/octet-stream' will be used.
+    # @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.
     def initialize(files, chunks, filename, mode, opts={})
       @files      = files
       @chunks     = chunks

lib/mongo/gridfs/grid_store.rb

@@ -47,7 +47,6 @@ module GridFS
   #    puts f.read
   #  end
   #
-  # @core gridfs
   # @deprecated
   class GridStore
     include Enumerable