Skip to content

Commit 191e9b2

Browse files
estolfoestolfo
committed
yardoc updates
1 parent 2a109c8 commit 191e9b2

File tree

9 files changed

+90
-91
lines changed

9 files changed

+90
-91
lines changed

‎lib/mongo/collection.rb‎

Lines changed: 41 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,21 @@ class Collection
3737
#
3838
# @param [String, Symbol] name the name of the collection.
3939
# @param [DB] db a MongoDB database instance.
40+
#
41+
# @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
42+
# should be acknowledged
43+
# @option opts [Boolean] :j (false) Set journal acknowledgement
44+
# @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
45+
# @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
46+
#
47+
# Notes about write concern:
48+
# These write concern options will be used for insert, update, and remove methods called on this
49+
# Collection instance. If no value is provided, the default values set on this instance's DB will be used.
50+
# These option values can be overridden for any invocation of insert, update, or remove.
4051
#
4152
# @option opts [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
42-
# other than the default BSON::ObjectId.
43-
#
44-
# @option opts [Hash] :w, :j, :wtimeout, :fsync Set the default write concern
45-
# for +insert+, +update+, and +remove+ method called on this Collection instance. If no
46-
# value is provided, the default values set on this instance's DB will be used. These option
47-
# values can be overridden for any invocation of +insert+, +update+, or +remove+.
48-
# @option options [:primary, :secondary] :read The default read preference for queries
53+
# other than the default BSON::ObjectId.
54+
# @option opts [:primary, :secondary] :read The default read preference for queries
4955
# initiates from this connection object. If +:secondary+ is chosen, reads will be sent
5056
# to one of the closest available secondary nodes. If a secondary node cannot be located, the
5157
# 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={})
326332
# :fsync will confirm that a write has been fsynced.
327333
# Options provided here will override any write concern options set on this collection,
328334
# its database object, or the current connection. See the options
329-
# for +DB#get_last_error+.
335+
# for DB#get_last_error.
330336
#
331337
# @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
332338
def save(doc, opts={})
@@ -351,14 +357,15 @@ def save(doc, opts={})
351357
# 2nd, a list of invalid documents.
352358
# Return this result format only when :collect_on_error is true.
353359
#
354-
# @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
355-
# :w > 0 will run a +getlasterror+ command on the database to report any assertion.
356-
# :j will confirm a write has been committed to the journal,
357-
# :wtimeout specifies how long to wait for write confirmation,
358-
# :fsync will confirm that a write has been fsynced.
359-
# Options provided here will override any write concern options set on this collection,
360-
# its database object, or the current connection. See the options
361-
# for +DB#get_last_error+.
360+
# @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
361+
# should be acknowledged
362+
# @option opts [Boolean] :j (false) Set journal acknowledgement
363+
# @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
364+
# @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
365+
#
366+
# Notes on write concern:
367+
# Options provided here will override any write concern options set on this collection,
368+
# its database object, or the current connection. See the options for +DB#get_last_error+.
362369
#
363370
# @option opts [Boolean] :continue_on_error (+false+) If true, then
364371
# continue a bulk insert even if one of the documents inserted
@@ -388,14 +395,15 @@ def insert(doc_or_docs, opts={})
388395
# @param [Hash] selector
389396
# If specified, only matching documents will be removed.
390397
#
391-
# @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
392-
# :w > 0 will run a +getlasterror+ command on the database to report any assertion.
393-
# :j will confirm a write has been committed to the journal,
394-
# :wtimeout specifies how long to wait for write confirmation,
395-
# :fsync will confirm that a write has been fsynced.
396-
# Options provided here will override any write concern options set on this collection,
397-
# its database object, or the current connection. See the options
398-
# for +DB#get_last_error+.
398+
# @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
399+
# should be acknowledged
400+
# @option opts [Boolean] :j (false) Set journal acknowledgement
401+
# @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
402+
# @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
403+
#
404+
# Notes on write concern:
405+
# Options provided here will override any write concern options set on this collection,
406+
# its database object, or the current connection. See the options for +DB#get_last_error+.
399407
#
400408
# @example remove all documents from the 'users' collection:
401409
# users.remove
@@ -441,14 +449,15 @@ def remove(selector={}, opts={})
441449
# @option opts [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
442450
# @option opts [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
443451
# just the first matching document. Note: only works in MongoDB 1.1.3 or later.
444-
# @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
445-
# :w > 0 will run a +getlasterror+ command on the database to report any assertion.
446-
# :j will confirm a write has been committed to the journal,
447-
# :wtimeout specifies how long to wait for write confirmation,
448-
# :fsync will confirm that a write has been fsynced.
449-
# Options provided here will override any write concern options set on this collection,
450-
# its database object, or the current connection. See the options
451-
# for +DB#get_last_error+.
452+
# @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
453+
# should be acknowledged
454+
# @option opts [Boolean] :j (false) Set journal acknowledgement
455+
# @option opts [Integer] :wtimeout (false) Set replica set acknowledgement timeout
456+
# @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
457+
#
458+
# Notes on write concern:
459+
# Options provided here will override any write concern options set on this collection,
460+
# its database object, or the current connection. See the options for DB#get_last_error.
452461
#
453462
# @return [Hash, true] Returns a Hash containing the last error object if acknowledging writes.
454463
# Otherwise, returns true.

‎lib/mongo/db.rb‎

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

‎lib/mongo/gridfs/grid.rb‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,11 @@ def initialize(db, fs_name=DEFAULT_FS_NAME)
6262
# the content type will may be inferred from the filename extension if the mime-types gem can be
6363
# loaded. Otherwise, the content type 'binary/octet-stream' will be used.
6464
# @option opts [Integer] (262144) :chunk_size size of file chunks in bytes.
65-
# @option opts [Boolean] :w (1) Set the write concern
66-
# When :w > 0, the chunks sent to the server are validated using an md5 hash.
67-
# If validation fails, an exception will be raised.
65+
# @option opts [String, Integer, Symbol] :w (1) Set write concern
66+
#
67+
# Notes on write concern:
68+
# When :w > 0, the chunks sent to the server are validated using an md5 hash.
69+
# If validation fails, an exception will be raised.
6870
#
6971
# @return [BSON::ObjectId] the file's id.
7072
def put(data, opts={})

‎lib/mongo/gridfs/grid_file_system.rb‎

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

‎lib/mongo/gridfs/grid_io.rb‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,11 @@ class GridIO
5050
# @option opts [String] :content_type ('binary/octet-stream') If no content type is specified,
5151
# the content type will may be inferred from the filename extension if the mime-types gem can be
5252
# loaded. Otherwise, the content type 'binary/octet-stream' will be used.
53-
# @option opts [Hash] :w (1) Set the default write concern
54-
# When :w > 0, the chunks sent to the server
55-
# will be validated using an md5 hash. If validation fails, an exception will be raised.
53+
# @option opts [String, Integer, Symbol] :w (1) Set the write concern
54+
#
55+
# Notes on write concern:
56+
# When :w > 0, the chunks sent to the server
57+
# will be validated using an md5 hash. If validation fails, an exception will be raised.
5658
def initialize(files, chunks, filename, mode, opts={})
5759
@files = files
5860
@chunks = chunks

‎lib/mongo/legacy.rb‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ def self.from_uri(uri = ENV['MONGODB_URI'], extra_opts={})
4343

4444
module Mongo
4545
# @deprecated Use Mongo::MongoClient instead. Support will be removed after v2.0
46+
# Please see old documentation for the Connection class
4647
class Connection < MongoClient
4748
include Mongo::LegacyWriteConcern
4849

@@ -53,6 +54,7 @@ def initialize(host=nil, port=nil, opts={})
5354
end
5455

5556
# @deprecated Use Mongo::MongoReplicaSetClient instead. Support will be removed after v2.0
57+
# Please see old documentation for the ReplSetConnection class
5658
class ReplSetConnection < MongoReplicaSetClient
5759
include Mongo::LegacyWriteConcern
5860

@@ -67,6 +69,7 @@ def initialize(*args)
6769
end
6870

6971
# @deprecated Use Mongo::MongoShardedClient instead. Support will be removed after v2.0
72+
# Please see old documentation for the ShardedConnection class
7073
class ShardedConnection < MongoShardedClient
7174
include Mongo::LegacyWriteConcern
7275

‎lib/mongo/mongo_client.rb‎

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

‎lib/mongo/mongo_replica_set_client.rb‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,16 @@ class MongoReplicaSetClient < MongoClient
5353
# @overload initialize(seeds=ENV["MONGODB_URI"], opts={})
5454
# @param [Array<String>, Array<Array(String, Integer)>] seeds
5555
#
56-
# @option opts [Hash] :w (1), :j (false), :wtimeout (false), :fsync (false) Set the default write concern
57-
# propagated to DB objects instantiated off of this MongoReplicaSetClient. This
58-
# default can be overridden upon instantiation of any DB by explicitly setting write concern values
59-
# on initialization.
56+
# @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
57+
# should be acknowledged
58+
# @option opts [Boolean] :j (false) Set journal acknowledgement
59+
# @option opts [Integer] :wtimeout (false) Set acknowledgement timeout
60+
# @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
61+
#
62+
# Notes about write concern options:
63+
# Write concern options are propagated to objects instantiated from this MongoReplicaSetClient.
64+
# These defaults can be overridden upon instantiation of any object by explicitly setting an options hash
65+
# on initialization.
6066
# @option opts [:primary, :primary_preferred, :secondary, :secondary_preferred, :nearest] :read_preference (:primary)
6167
# A "read preference" determines the candidate replica set members to which a query or command can be sent.
6268
# [:primary]

‎lib/mongo/mongo_sharded_client.rb‎

Lines changed: 0 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -26,43 +26,6 @@ class MongoShardedClient < MongoReplicaSetClient
2626
attr_reader :seeds, :refresh_interval, :refresh_mode,
2727
:refresh_version, :manager
2828

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

0 commit comments

Comments
 (0)