minor: doc updates. added ydoc rake task

This commit is contained in:
Kyle Banker 2010-01-07 18:35:18 -05:00
parent 1e183d1f53
commit 4024a5b333
4 changed files with 65 additions and 38 deletions

View File

@ -82,18 +82,27 @@ Note that the GridStore class is not automatically required when you require
Example code: 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!" f.puts "Hello, world!"
} end
GridStore.open(database, 'filename, 'r') { |f|
puts f.read # => Hello, world!\n # Output "Hello, world!"
} GridStore.open(database, 'filename, 'r') do |f|
GridStore.open(database, 'filename', 'w+') { |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!" f.puts "But wait, there's more!"
} end
GridStore.open(database, 'filename, 'r') { |f|
puts f.read # => Hello, world!\nBut wait, there's more!\n # Retrieve everything, outputting "Hello, world!\nBut wait, there's more!\n"
} GridStore.open(database, 'filename, 'r') do |f|
puts f.read
end
= Notes = Notes
@ -119,7 +128,7 @@ A pooled connection to a paired instance would look like this:
:right => ["db2.example.com", 27017]}, nil, :right => ["db2.example.com", 27017]}, nil,
:pool_size => 20, :timeout => 5) :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. to the connection pooling implementations in ActiveRecord and PyMongo.
== Using with Phusion Passenger == Using with Phusion Passenger
@ -139,7 +148,7 @@ or handle reconnecting when passenger forks a new process:
end end
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. script.
See this thread[http://groups.google.com/group/mongodb-user/browse_thread/thread/f31e2d23de38136a] 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 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 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. string.
== Primary Keys == 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. using a PK factory lets you do so.
You can tell the Ruby Mongo driver how to create primary keys by passing in 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 = Mongo::Connection.new.db('dbname', :pk_factory => MyPKFactory.new)
db = Connection.new.db('dbname', :pk => MyPKFactory.new)
A primary key factory object must respond to :create_pk, which should take a 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 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 fields the factory wishes to inject.
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 NOTE: if the object already has a primary key, the factory should not inject
a record is inserted, the :pk object's +create_pk+ method will be called and 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. the new hash returned will be inserted.
Here is a sample primary key factory, taken from the tests: 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. - Cursors have a to_a method.
= Testing = Testing
If you have the source code, you can run the tests. There's a separate rake task for testing with If you have the source code, you can run the tests. There's a separate rake task for testing with

View File

@ -83,6 +83,14 @@ task :rdoc do
system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`" system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
end 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" desc "Publish documentation to mongo.rubyforge.org"
task :publish => [:rdoc] do task :publish => [:rdoc] do
# Assumes docs are in ./html # Assumes docs are in ./html

View File

@ -15,5 +15,8 @@
# ++ # ++
require 'mongo/gridfs/grid_store' 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 module GridFS
end end

View File

@ -20,25 +20,32 @@ require 'mongo/gridfs/chunk'
module GridFS module GridFS
# GridStore is an IO-like object that provides input and output for # GridStore is an IO-like class that provides input and output for
# streams of data to Mongo. See Mongo's documentation about GridFS for # streams of data to MongoDB.
# storage implementation details.
# #
# Example code: # @example
# #
# require 'mongo/gridfs' # include GridFS
# GridStore.open(database, 'filename', 'w') { |f| #
# #Store the text "Hello, world!" in the grid store.
# GridStore.open(database, 'filename', 'w') do |f|
# f.puts "Hello, world!" # f.puts "Hello, world!"
# } # end
# GridStore.open(database, 'filename, 'r') { |f| #
# puts f.read # => Hello, world!\n # # Output "Hello, world!"
# } # GridStore.open(database, 'filename, 'r') do |f|
# GridStore.open(database, 'filename', 'w+') { |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!" # f.puts "But wait, there's more!"
# } # end
# GridStore.open(database, 'filename, 'r') { |f| #
# puts f.read # => Hello, world!\nBut wait, there's more!\n # # Retrieve everything, outputting "Hello, world!\nBut wait, there's more!\n"
# } # GridStore.open(database, 'filename, 'r') do |f|
# puts f.read
# end
class GridStore class GridStore
DEFAULT_ROOT_COLLECTION = 'fs' DEFAULT_ROOT_COLLECTION = 'fs'