RUBY-1924 Documentation improvements to support auto encryption implementation

lib/mongo/protocol/compressed.rb

@@ -60,15 +60,13 @@ def initialize(message, compressor, zlib_compression_level = nil)
         @request_id = message.request_id
       end
 
-      # Inflate an OP_COMRESSED message and return the original message.
-      #
-      # @example Inflate a compressed message.
-      #  message.inflate!
+      # Inflates an OP_COMRESSED message and returns the original message.
       #
       # @return [ Protocol::Message ] The inflated message.
       #
       # @since 2.5.0
-      def inflate!
+      # @api private
+      def maybe_inflate
         message = Registry.get(@original_op_code).allocate
         uncompressed_message = Zlib::Inflate.inflate(@compressed_message)
 

lib/mongo/protocol/insert.rb

@@ -46,8 +46,10 @@ class Insert < Message
       # @param options [Hash] Additional options for the insertion.
       #
       # @option options :flags [Array] The flags for the insertion message.
-      #
       #   Supported flags: +:continue_on_error+
+      # @option options [ true, false ] validating_keys Whether keys should be
+      #   validated for being valid document keys (i.e. not begin with $ and
+      #   not contain dots).
       def initialize(database, collection, documents, options = {})
         @database = database
         @namespace = "#{database}.#{collection}"

lib/mongo/protocol/message.rb

@@ -129,13 +129,14 @@ def maybe_compress(compressor, zlib_compression_level = nil)
         end
       end
 
-      # Inflate a message.
+      # Inflate a message if it is compressed.
       #
-      # @return [ self ] Always returns self. Other message types should
-      #   override this method.
+      # @return [ Protocol::Message ] Always returns self. Subclasses should
+      #   override this method as necessary.
       #
       # @since 2.5.0
-      def inflate!
+      # @api private
+      def maybe_inflate
         self
       end
 
@@ -183,7 +184,7 @@ def self.deserialize(io, max_message_size = MAX_MESSAGE_SIZE, expected_response_
             deserialize_field(message, buffer, field)
           end
         end
-        message.inflate!
+        message.maybe_inflate
       end
 
       # Tests for equality between two wire protocol messages

lib/mongo/protocol/msg.rb

@@ -44,16 +44,17 @@ class Msg < Message
       #           { type: 1, payload: { identifier: 'documents', sequence: [..] } })
       #
       # @param [ Array<Symbol> ] flags The flag bits. Current supported values
-      # are :more_to_come and :checksum_present.
-      # @param [ Hash ] options The options. There are currently no supported
-      #   options, this is a placeholder for the future.
+      #   are :more_to_come and :checksum_present.
+      # @param [ Hash ] options The options.
       # @param [ BSON::Document, Hash ] global_args The global arguments,
       #   becomes a section of payload type 0.
       # @param [ BSON::Document, Hash ] sections Zero or more sections, in the format
       #   { type: 1, payload: { identifier: <String>, sequence: <Array<BSON::Document, Hash>> } } or
       #   { type: 0, payload: <BSON::Document, Hash> }
       #
-      # @option options [ true, false ] validating_keys Whether keys should be validated.
+      # @option options [ true, false ] validating_keys Whether keys should be
+      #   validated for being valid document keys (i.e. not begin with $ and
+      #   not contain dots).
       #
       # @api private
       #
@@ -92,7 +93,7 @@ def payload
         # https://jira.mongodb.org/browse/RUBY-1591.
         # Note that even without the reordering, the payload is not an exact
         # match to what is sent over the wire because the command as used in
-        # the published eent combines keys from multiple sections of the
+        # the published event combines keys from multiple sections of the
         # payload sent over the wire.
         ordered_command = {}
         skipped_command = {}
@@ -110,7 +111,7 @@ def payload
           database_name: global_args[DATABASE_IDENTIFIER],
           command: ordered_command,
           request_id: request_id,
-          reply: sections[0]
+          reply: sections[0],
         )
       end
 

lib/mongo/server/connection_pool.rb

@@ -347,7 +347,8 @@ def check_out
                   "from pool for #{@server.address} after #{wait_timeout} sec. " +
                   "Connections in pool: #{@available_connections.length} available, " +
                   "#{@checked_out_connections.length} checked out, " +
-                  "#{@pending_connections.length} pending"
+                  "#{@pending_connections.length} pending " +
+                  "(max size: #{max_size})"
               end
               raise Error::ConnectionCheckOutTimeout.new(msg, address: @server.address)
             end