From 4024a5b333eb77e76af58ec4ef89421478bc9651 Mon Sep 17 00:00:00 2001 From: Kyle Banker Date: Thu, 7 Jan 2010 18:35:18 -0500 Subject: [PATCH] minor: doc updates. added ydoc rake task --- README.rdoc | 51 ++++++++++++++++++++-------------- Rakefile | 8 ++++++ lib/mongo/gridfs.rb | 3 ++ lib/mongo/gridfs/grid_store.rb | 41 +++++++++++++++------------ 4 files changed, 65 insertions(+), 38 deletions(-) diff --git a/README.rdoc b/README.rdoc index fe66517..87458d7 100644 --- a/README.rdoc +++ b/README.rdoc @@ -82,18 +82,27 @@ Note that the GridStore class is not automatically required when you require Example code: - GridStore.open(database, 'filename', 'w') { |f| + include GridFS + + # Store the text "Hello, world!" in the grid store. + GridStore.open(database, 'filename', 'w') do |f| f.puts "Hello, world!" - } - GridStore.open(database, 'filename, 'r') { |f| - puts f.read # => Hello, world!\n - } - GridStore.open(database, 'filename', 'w+') { |f| + end + + # Output "Hello, world!" + GridStore.open(database, 'filename, 'r') do |f| + puts f.read + end + + # Add text to the grid store. + GridStore.open(database, 'filename', 'w+') do |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 - } + end + + # Retrieve everything, outputting "Hello, world!\nBut wait, there's more!\n" + GridStore.open(database, 'filename, 'r') do |f| + puts f.read + end = Notes @@ -119,7 +128,7 @@ A pooled connection to a paired instance would look like this: :right => ["db2.example.com", 27017]}, nil, :pool_size => 20, :timeout => 5) -Though the pooling architecure will undoubtedly evolve, it owes much credit +Though the pooling architecure will undoubtedly evolve, it currently owes much credit to the connection pooling implementations in ActiveRecord and PyMongo. == Using with Phusion Passenger @@ -139,7 +148,7 @@ or handle reconnecting when passenger forks a new process: end end -The above code should be put in _environment.rb_ or an initialization +The above code should be put in _environment.rb_ or in an initialization script. See this thread[http://groups.google.com/group/mongodb-user/browse_thread/thread/f31e2d23de38136a] @@ -156,7 +165,7 @@ read from Mongo will have their character encodings set to UTF-8. When used with Ruby 1.8, the bytes in each string are written to and read from Mongo as-is. If the string is ASCII all is well, because ASCII is a subset of -UTF-8. If the string is not ASCII then it may not be a well-formed UTF-8 +UTF-8. If the string is not ASCII, it may not be a well-formed UTF-8 string. == Primary Keys @@ -173,17 +182,18 @@ generate _id values. If you want to control _id values or even their types, using a PK factory lets you do so. You can tell the Ruby Mongo driver how to create primary keys by passing in -the :pk option to the Connection#db method. +the :pk_factory option to the Connection#db method. - include Mongo - db = Connection.new.db('dbname', :pk => MyPKFactory.new) + db = Mongo::Connection.new.db('dbname', :pk_factory => MyPKFactory.new) A primary key factory object must respond to :create_pk, which should take a hash and return a hash which merges the original hash with any primary key -fields the factory wishes to inject. NOTE: if the object already has a primary -key, the factory should not inject a new key; this means that the object is -being used in a repsert but it already exists. The idea here is that whenever -a record is inserted, the :pk object's +create_pk+ method will be called and +fields the factory wishes to inject. + +NOTE: if the object already has a primary key, the factory should not inject +a new key; this means that the object is being used in a repsert but it already +exists. The idea here is that whenever a record is inserted, +the :pk_factory object's +create_pk+ method will be called and the new hash returned will be inserted. Here is a sample primary key factory, taken from the tests: @@ -251,7 +261,6 @@ Random cursor fun facts: - Cursors have a to_a method. - = Testing If you have the source code, you can run the tests. There's a separate rake task for testing with diff --git a/Rakefile b/Rakefile index 33fbe77..0ff3079 100644 --- a/Rakefile +++ b/Rakefile @@ -83,6 +83,14 @@ task :rdoc do system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`" end +desc "Generate YARD documentation" +task :ydoc do + version = eval(File.read("mongo-ruby-driver.gemspec")).version + out = File.join('ydoc', version.to_s) + FileUtils.rm_rf('ydoc') + system "yardoc lib/**/*.rb lib/mongo/**/*.rb -o #{out} --title MongoRuby-#{version}" +end + desc "Publish documentation to mongo.rubyforge.org" task :publish => [:rdoc] do # Assumes docs are in ./html diff --git a/lib/mongo/gridfs.rb b/lib/mongo/gridfs.rb index a5f978b..d02c306 100644 --- a/lib/mongo/gridfs.rb +++ b/lib/mongo/gridfs.rb @@ -15,5 +15,8 @@ # ++ require 'mongo/gridfs/grid_store' +# GridFS is a specification for storing large binary objects in MongoDB. +# See the documentation for GridFS::GridStore +# @see GridFS::GridStore module GridFS end diff --git a/lib/mongo/gridfs/grid_store.rb b/lib/mongo/gridfs/grid_store.rb index f7b2d85..f12cc9d 100644 --- a/lib/mongo/gridfs/grid_store.rb +++ b/lib/mongo/gridfs/grid_store.rb @@ -20,25 +20,32 @@ require 'mongo/gridfs/chunk' module GridFS - # GridStore is an IO-like object that provides input and output for - # streams of data to Mongo. See Mongo's documentation about GridFS for - # storage implementation details. + # GridStore is an IO-like class that provides input and output for + # streams of data to MongoDB. # - # Example code: + # @example # - # 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| - # f.puts "But wait, there's more!" - # } - # GridStore.open(database, 'filename, 'r') { |f| - # puts f.read # => Hello, world!\nBut wait, there's more!\n - # } + # include GridFS + # + # #Store the text "Hello, world!" in the grid store. + # GridStore.open(database, 'filename', 'w') do |f| + # f.puts "Hello, world!" + # end + # + # # Output "Hello, world!" + # GridStore.open(database, 'filename, 'r') do |f| + # puts f.read + # end + # + # # Add text to the grid store. + # GridStore.open(database, 'filename', 'w+') do |f| + # f.puts "But wait, there's more!" + # end + # + # # Retrieve everything, outputting "Hello, world!\nBut wait, there's more!\n" + # GridStore.open(database, 'filename, 'r') do |f| + # puts f.read + # end class GridStore DEFAULT_ROOT_COLLECTION = 'fs'