RUBY-705 Clean up API documentation

Author: estolfo

README.md

@@ -7,13 +7,17 @@ Installation
 
 **Gem Installation**<br>
 The Ruby driver is released and distributed through RubyGems and it can be installed with the following command:
+
 ```bash
 gem install mongo
 ```
+
 For a significant performance boost, you'll want to install the C-extension:
+
 ```bash
 gem install bson_ext
 ```
+
 **Github Installation**<br>
 For development and test environments (not recommended for production) you can also install the Ruby driver directly from source:
 
@@ -36,6 +40,7 @@ rake install
 Usage
 -----
 Here is a quick example of basic usage for the Ruby driver:
+
 ```ruby
 require 'mongo'
 include Mongo

lib/bson/types/binary.rb

@@ -35,7 +35,7 @@ class Binary < ByteBuffer
     #
     # @param [Array, String] data to story as BSON binary. If a string is given, the on
     #   Ruby 1.9 it will be forced to the binary encoding.
-    # @param [Fixnum] one of four values specifying a BSON binary subtype. Possible values are
+    # @param [Fixnum] subtype one of four values specifying a BSON binary subtype. Possible values are
     #   SUBTYPE_BYTES, SUBTYPE_UUID, SUBTYPE_MD5, and SUBTYPE_USER_DEFINED.
     #
     # @see http://www.mongodb.org/display/DOCS/BSON#BSON-noteondatabinary BSON binary subtypes.

lib/bson/types/code.rb

@@ -23,7 +23,7 @@ class Code
     # Wrap code to be evaluated by MongoDB.
     #
     # @param [String] code the JavaScript code.
-    # @param [Hash] a document mapping identifiers to values, which
+    # @param [Hash] scope a document mapping identifiers to values, which
     #   represent the scope in which the code is to be executed.
     def initialize(code, scope={})
       @code  = code

lib/bson/types/dbref.rb

@@ -21,8 +21,8 @@ class DBRef
 
     # Create a DBRef. Use this class in conjunction with DB#dereference.
     #
-    # @param [String] a collection name
-    # @param [ObjectId] an object id
+    # @param [String] namespace a collection name.
+    # @param [ObjectId] object_id an object id.
     def initialize(namespace, object_id)
       @namespace = namespace
       @object_id = object_id

lib/bson/types/regex.rb

@@ -32,7 +32,7 @@ class Regex
     # Create a new regexp.
     #
     # @param pattern [String]
-    # @param options [Array, String]
+    # @param opts [Array, String]
     def initialize(pattern, *opts)
       @pattern = pattern
       @options = opts.first.is_a?(Fixnum) ? opts.first : str_opts_to_int(opts.join)

lib/mongo/collection.rb

@@ -159,7 +159,7 @@ def hint=(hint=nil)
     end
 
     # Set a hint field using a named index.
-    # @param [String] hinted index name
+    # @param [String] hint index name
     def named_hint=(hint=nil)
       @hint = hint
       self

lib/mongo/cursor.rb

@@ -189,7 +189,7 @@ def has_next?
 
     # Get the size of the result set for this query.
     #
-    # @param [Boolean] whether of not to take notice of skip and limit
+    # @param [Boolean] skip_and_limit whether or not to take skip or limit into account.
     #
     # @return [Integer] the number of objects in the result set for this query.
     #

lib/mongo/functional/authentication.rb

@@ -296,7 +296,7 @@ def issue_gssapi(auth, opts={})
 
     # Helper to fetch a nonce value from a given database instance.
     #
-    # @param db [Mongo::DB] The DB instance to use for issue the nonce command.
+    # @param database [Mongo::DB] The DB instance to use for issue the nonce command.
     # @param opts [Hash] Hash of optional settings and configuration values.
     #
     # @option opts [Socket] socket (nil) Optional socket instance to use.

lib/mongo/functional/uri_parser.rb

@@ -153,8 +153,6 @@ class URIParser
     # @note Passwords can contain any character except for ','
     #
     # @param [String] uri The MongoDB URI string.
-    # @param [Hash,nil] extra_opts Extra options. Will override anything
-    #   already specified in the URI.
     def initialize(uri)
       if uri.start_with?('mongodb://')
         uri = uri[10..-1]

lib/mongo/gridfs/grid.rb

@@ -81,7 +81,7 @@ def put(data, opts={})
 
     # Read a file from the file store.
     #
-    # @param [] id the file's unique id.
+    # @param id the file's unique id.
     #
     # @return [Mongo::GridIO]
     def get(id)
@@ -95,7 +95,7 @@ def get(id)
     # is attempting to read a file while it's being deleted. While the odds for this
     # kind of race condition are small, it's important to be aware of.
     #
-    # @param [] id
+    # @param id
     #
     # @return [Boolean]
     def delete(id)

lib/mongo/gridfs/grid_io.rb

@@ -106,11 +106,9 @@ def read(length=nil)
 
     # Write the given string (binary) data to the file.
     #
-    # @param [String] string
-    #   the data to write
+    # @param [String] io the data to write.
     #
-    # @return [Integer]
-    #   the number of bytes written.
+    # @return [Integer] the number of bytes written.
     def write(io)
       raise GridError, "file not opened for write" unless @mode[0] == ?w
       if io.is_a? String

lib/mongo/mongo_client.rb

@@ -216,7 +216,7 @@ def self.multi(nodes, opts={})
     # @param uri [String]
     #   A string of the format mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/database]
     #
-    # @param opts Any of the options available for MongoClient.new
+    # @param [Hash] extra_opts Any of the options available for MongoClient.new
     #
     # @return [Mongo::MongoClient, Mongo::MongoReplicaSetClient]
     def self.from_uri(uri = ENV['MONGODB_URI'], extra_opts={})

lib/mongo/mongo_sharded_client.rb

@@ -148,10 +148,10 @@ def checkout(&block)
     # @param uri [ String ]  string of the format:
     #   mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/database]
     #
-    # @param opts [ Hash ] Any of the options available for MongoShardedClient.new
+    # @param options [ Hash ] Any of the options available for MongoShardedClient.new
     #
     # @return [ Mongo::MongoShardedClient ] The sharded client.
-    def self.from_uri(uri, options = {})
+    def self.from_uri(uri, options={})
       uri ||= ENV['MONGODB_URI']
       URIParser.new(uri).connection(options, false, true)
     end

lib/mongo/networking.rb

@@ -67,8 +67,8 @@ def send_message(operation, message, opts={})
     # @param [Integer] operation a MongoDB opcode.
     # @param [BSON::ByteBuffer] message a message to send to the database.
     # @param [String] db_name the name of the database. used on call to get_last_error.
-    # @param [Hash] last_error_params parameters to be sent to getLastError. See DB#error for
-    #   available options.
+    # @param [String] log_message this is currently a no-op and will be removed.
+    # @param [Hash] write_concern write concern.
     #
     # @see DB#get_last_error for valid last error params.
     #
@@ -122,8 +122,10 @@ def send_message_with_gle(operation, message, db_name, log_message=nil, write_co
     # @param [Socket] socket a socket to use in lieu of checking out a new one.
     # @param [Boolean] command (false) indicate whether this is a command. If this is a command,
     #   the message will be sent to the primary node.
-    # @param [Boolean] command (false) indicate whether the cursor should be exhausted. Set
+    # @param [Symbol] read the read preference.
+    # @param [Boolean] exhaust (false) indicate whether the cursor should be exhausted. Set
     #   this to true only when the OP_QUERY_EXHAUST flag is set.
+    # @param [Boolean] compile_regex whether BSON regex objects should be compiled into Ruby regexes.
     #
     # @return [Array]
     #   An array whose indexes include [0] documents returned, [1] number of document received,