yardoc updates

Author: estolfo

lib/mongo/collection.rb

@@ -37,15 +37,21 @@ class Collection
     #
     # @param [String, Symbol] name the name of the collection.
     # @param [DB] db a MongoDB database instance.
+    # 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #   
+    #   Notes about write concern:
+    #     These write concern options will be used for insert, update, and remove methods called on this  
+    #     Collection instance. If no value is provided, the default values set on this instance's DB will be used. 
+    #     These option values can be overridden for any invocation of insert, update, or remove.
     #
     # @option opts [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
-    #   other than the default BSON::ObjectId.
-    #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the default write concern
-    #   for +insert+, +update+, and +remove+ method called on this Collection instance. If no
-    #   value is provided, the default values set on this instance's DB will be used. These option 
-    #   values can be overridden for any invocation of +insert+, +update+, or +remove+.
-    # @option options [:primary, :secondary] :read The default read preference for queries
+    #   other than the default BSON::ObjectId. 
+    # @option opts [:primary, :secondary] :read The default read preference for queries
     #   initiates from this connection object. If +:secondary+ is chosen, reads will be sent
     #   to one of the closest available secondary nodes. If a secondary node cannot be located, the
     #   read will be sent to the primary. If this option is left unspecified, the value of the read
@@ -326,7 +332,7 @@ def find_one(spec_or_object_id=nil, opts={})
     #   :fsync will confirm that a write has been fsynced. 
     #   Options provided here will override any write concern options set on this collection,
     #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+.
+    #   for DB#get_last_error.
     #
     # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     def save(doc, opts={})
@@ -351,14 +357,15 @@ def save(doc, opts={})
     #   2nd, a list of invalid documents.
     #   Return this result format only when :collect_on_error is true.
     #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #   
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+. 
     #
     # @option opts [Boolean] :continue_on_error (+false+) If true, then
     #   continue a bulk insert even if one of the documents inserted
@@ -388,14 +395,15 @@ def insert(doc_or_docs, opts={})
     # @param [Hash] selector
     #   If specified, only matching documents will be removed.
     #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+. 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+.  
     #
     # @example remove all documents from the 'users' collection:
     #   users.remove
@@ -441,14 +449,15 @@ def remove(selector={}, opts={})
     # @option opts [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
     # @option opts [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
     #   just the first matching document. Note: only works in MongoDB 1.1.3 or later.
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+. 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for DB#get_last_error. 
     #
     # @return [Hash, true] Returns a Hash containing the last error object if acknowledging writes.
     #   Otherwise, returns true.

lib/mongo/db.rb

@@ -71,11 +71,17 @@ def strict?; @strict; end
     #   fields the factory wishes to inject. (NOTE: if the object already has a primary key,
     #   the factory should not inject a new key).
     #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the default write concern for this database.
-    #   Propagated to Collection objects instantiated off of this DB. If no
-    #   options are provided, the default write concern set on this instance's MongoClient object will be used. This
-    #   default can be overridden upon instantiation of any collection by explicitly setting write concern values
-    #   on initialization
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #   Notes on write concern:
+    #     These write concern options are propagated to Collection objects instantiated off of this DB. If no
+    #     options are provided, the default write concern set on this instance's MongoClient object will be used. This
+    #     default can be overridden upon instantiation of any collection by explicitly setting write concern options
+    #     on initialization or at the time of an operation.
     #
     # @option opts [Integer] :cache_time (300) Set the time that all ensure_index calls should cache the command.
     #

lib/mongo/gridfs/grid.rb

@@ -62,9 +62,11 @@ def initialize(db, fs_name=DEFAULT_FS_NAME)
     #   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.
     # @option opts [Integer] (262144) :chunk_size size of file chunks in bytes.
-    # @option opts [Boolean] :w (1) Set the write concern
-    #   When :w > 0, the chunks sent to the server are validated using an md5 hash. 
-    #   If validation fails, an exception will be raised.
+    # @option opts [String, Integer, Symbol] :w (1) Set write concern
+    #
+    #   Notes on write concern:  
+    #      When :w > 0, the chunks sent to the server are validated using an md5 hash. 
+    #      If validation fails, an exception will be raised.
     #
     # @return [BSON::ObjectId] the file's id.
     def put(data, opts={})

lib/mongo/gridfs/grid_file_system.rb

@@ -69,9 +69,11 @@ def initialize(db, fs_name=Grid::DEFAULT_FS_NAME)
     # @option opts [Boolean] :delete_old (false) ensure that old versions of the file are deleted. This option
     #  only work in 'w' mode. Certain precautions must be taken when deleting GridFS files. See the notes under
     #  GridFileSystem#delete.
-    # @option opts [Hash] :w (1) Set the write concern
-    #   When :w > 0, the chunks sent to the server
-    #   will be validated using an md5 hash. If validation fails, an exception will be raised.
+    # @option opts [String, Integer, Symbol] :w (1) Set write concern
+    #
+    #   Notes on write concern:
+    #     When :w > 0, the chunks sent to the server
+    #     will be validated using an md5 hash. If validation fails, an exception will be raised.
     # @option opts [Integer] :versions (false) deletes all versions which exceed the number specified to 
     #   retain ordered by uploadDate. This option only works in 'w' mode. Certain precautions must be taken when 
     #   deleting GridFS files. See the notes under GridFileSystem#delete.

lib/mongo/gridfs/grid_io.rb

@@ -50,9 +50,11 @@ class GridIO
     # @option 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.
-    # @option opts [Hash] :w (1) Set the default write concern
-    #   When :w > 0, the chunks sent to the server
-    #   will be validated using an md5 hash. If validation fails, an exception will be raised.
+    # @option opts [String, Integer, Symbol] :w (1) Set the write concern
+    #
+    #   Notes on write concern:
+    #     When :w > 0, 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/legacy.rb

@@ -43,6 +43,7 @@ def self.from_uri(uri = ENV['MONGODB_URI'], extra_opts={})
 
 module Mongo
   # @deprecated Use Mongo::MongoClient instead. Support will be removed after v2.0
+  # Please see old documentation for the Connection class
   class Connection < MongoClient
     include Mongo::LegacyWriteConcern
 
@@ -53,6 +54,7 @@ def initialize(host=nil, port=nil, opts={})
   end
 
   # @deprecated Use Mongo::MongoReplicaSetClient instead. Support will be removed after v2.0
+  # Please see old documentation for the ReplSetConnection class
   class ReplSetConnection < MongoReplicaSetClient
     include Mongo::LegacyWriteConcern
 
@@ -67,6 +69,7 @@ def initialize(*args)
   end
 
   # @deprecated Use Mongo::MongoShardedClient instead. Support will be removed after v2.0
+  # Please see old documentation for the ShardedConnection class
   class ShardedConnection < MongoShardedClient
     include Mongo::LegacyWriteConcern
 

lib/mongo/mongo_client.rb

@@ -75,10 +75,16 @@ class MongoClient
     # @param [String, Hash] host
     # @param [Integer] port specify a port number here if only one host is being specified.
     #
-    # @option opts [Hash] :w (1), :j (false), :wtimeout (false), :fsync (false) Set the default write concern
-    #   options propagated to DB objects instantiated off of this MongoClient.
-    #   This default can be overridden upon instantiation of any DB by explicitly setting an options hash
-    #   on initialization.  It can also be overridden at instantiation of a collection or at the time of a write operation.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #     Notes about write concern options:
+    #       Write concern options are propagated to objects instantiated from this MongoClient.
+    #       These defaults can be overridden upon instantiation of any object by explicitly setting an options hash
+    #       on initialization.
     # @option opts [Boolean] :slave_ok (false) Must be set to +true+ when connecting
     #   to a single, slave node.
     # @option opts [Logger, #debug] :logger (nil) A Logger instance for debugging driver ops. Note that

lib/mongo/mongo_replica_set_client.rb

@@ -53,10 +53,16 @@ class MongoReplicaSetClient < MongoClient
     # @overload initialize(seeds=ENV["MONGODB_URI"], opts={})
     #   @param [Array<String>, Array<Array(String, Integer)>] seeds
     #
-    #   @option opts [Hash] :w (1), :j (false), :wtimeout (false), :fsync (false) Set the default write concern
-    #     propagated to DB objects instantiated off of this MongoReplicaSetClient. This
-    #     default can be overridden upon instantiation of any DB by explicitly setting write concern values
-    #     on initialization.
+    #   @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #     should be acknowledged
+    #   @option opts [Boolean] :j (false) Set journal acknowledgement
+    #   @option opts [Integer] :wtimeout (false) Set acknowledgement timeout
+    #   @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #     Notes about write concern options:
+    #       Write concern options are propagated to objects instantiated from this MongoReplicaSetClient.
+    #       These defaults can be overridden upon instantiation of any object by explicitly setting an options hash
+    #       on initialization.
     #   @option opts [:primary, :primary_preferred, :secondary, :secondary_preferred, :nearest] :read_preference (:primary)
     #     A "read preference" determines the candidate replica set members to which a query or command can be sent.
     #     [:primary]

lib/mongo/mongo_sharded_client.rb

@@ -26,43 +26,6 @@ class MongoShardedClient < MongoReplicaSetClient
     attr_reader :seeds, :refresh_interval, :refresh_mode,
                 :refresh_version, :manager
 
-    # Create a connection to a MongoDB sharded cluster.
-    #
-    # If no args are provided, it will check <code>ENV["MONGODB_URI"]</code>.
-    #
-    # @param [Array] seeds "host:port" strings
-    #
-    # @option opts [String] :name (nil) The name of the sharded cluster to connect to. You
-    #   can use this option to verify that you're connecting to the right sharded cluster.
-    # @option opts [Hash] ::w (1), :j (false), :wtimeout (false), :fsync (false) Set the default write concern
-    #   propagated to DB objects instantiated off of this MongoClient. This
-    #   default can be overridden upon instantiation of any DB by explicitly setting a write concern values
-    #   on initialization.
-    # @option opts [Logger] :logger (nil) Logger instance to receive driver operation log.
-    # @option opts [Integer] :pool_size (1) The maximum number of socket connections allowed per
-    #   connection pool. Note: this setting is relevant only for multi-threaded applications.
-    # @option opts [Float] :pool_timeout (5.0) When all of the connections a pool are checked out,
-    #   this is the number of seconds to wait for a new connection to be released before throwing an exception.
-    #   Note: this setting is relevant only for multi-threaded applications.
-    # @option opts [Float] :op_timeout (nil) The number of seconds to wait for a read operation to time out.
-    # @option opts [Float] :connect_timeout (30) The number of seconds to wait before timing out a
-    #   connection attempt.
-    # @option opts [Boolean] :ssl (false) If true, create the connection to the server using SSL.
-    # @option opts [Boolean] :refresh_mode (false) Set this to :sync to periodically update the
-    #   state of the connection every :refresh_interval seconds. Sharded cluster connection failures
-    #   will always trigger a complete refresh. This option is useful when you want to add new nodes
-    #   or remove sharded cluster nodes not currently in use by the driver.
-    # @option opts [Integer] :refresh_interval (90) If :refresh_mode is enabled, this is the number of seconds
-    #   between calls to check the sharded cluster's state.
-    # Note: that the number of seed nodes does not have to be equal to the number of sharded cluster members.
-    # The purpose of seed nodes is to permit the driver to find at least one sharded cluster member even if a member is down.
-    #
-    # @example Connect to a sharded cluster and provide two seed nodes.
-    #   MongoShardedClient.new(['localhost:30000', 'localhost:30001'])
-    #
-    # @raise [MongoArgumentError] This is raised for usage errors.
-    #
-    # @raise [ConnectionFailure] This is raised for the various connection failures.
     def initialize(*args)
       opts = args.last.is_a?(Hash) ? args.pop : {}