mongo 2.13.1 → 2.14.0.rc1

data/lib/mongo/operation/indexes/result.rb

@@ -20,6 +20,7 @@ module Mongo
       # listIndexes command.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # Get the cursor id for the result.
@@ -35,6 +36,7 @@ module Mongo
         # @return [ Integer ] The cursor id.
         #
         # @since 2.0.0
+        # @api private
         def cursor_id
           cursor_document ? cursor_document[CURSOR_ID] : super
         end
@@ -47,6 +49,7 @@ module Mongo
         # @return [ String ] The namespace.
         #
         # @since 2.0.0
+        # @api private
         def namespace
           cursor_document ? cursor_document[NAMESPACE] : super
         end
@@ -60,6 +63,7 @@ module Mongo
         # @return [ Array<BSON::Document> ] The documents.
         #
         # @since 2.0.0
+        # @api public
         def documents
           cursor_document[FIRST_BATCH]
         end
@@ -77,6 +81,7 @@ module Mongo
         # @return [ Result ] Self if successful.
         #
         # @since 2.0.0
+        # @api private
         def validate!
           !successful? ? raise_operation_failure : self
         end

data/lib/mongo/operation/insert/bulk_result.rb

@@ -19,12 +19,14 @@ module Mongo
       # Defines custom behavior of results for an insert when sent as part of a bulk write.
       #
       # @since 2.0.0
+      # @api semiprivate
       class BulkResult < Operation::Result
         include Aggregatable
 
         # Get the ids of the inserted documents.
         #
         # @since 2.0.0
+        # @api public
         attr_reader :inserted_ids
 
         # Initialize a new result.
@@ -39,6 +41,7 @@ module Mongo
         # @param [ Array<Object> ] ids The ids of the inserted documents.
         #
         # @since 2.0.0
+        # @api private
         def initialize(replies, connection_description, ids)
           @replies = [*replies] if replies
           @connection_description = connection_description
@@ -83,6 +86,7 @@ module Mongo
         # @return [ Integer ] The number of documents inserted.
         #
         # @since 2.0.0
+        # @api public
         def n_inserted
           written_count
         end
@@ -95,6 +99,7 @@ module Mongo
         # @return [ Object ] The id of the document inserted.
         #
         # @since 2.0.0
+        # @api public
         def inserted_id
           inserted_ids.first
         end

data/lib/mongo/operation/insert/result.rb

@@ -22,11 +22,13 @@ module Mongo
       # is optional. It can be added to this class later, if needed.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # Get the ids of the inserted documents.
         #
         # @since 2.0.0
+        # @api public
         attr_reader :inserted_ids
 
         # Initialize a new result.
@@ -41,6 +43,7 @@ module Mongo
         # @param [ Array<Object> ] ids The ids of the inserted documents.
         #
         # @since 2.0.0
+        # @api private
         def initialize(replies, connection_description, ids)
           super(replies, connection_description)
           @inserted_ids = ids
@@ -54,10 +57,12 @@ module Mongo
         # @return [ Object ] The id of the document inserted.
         #
         # @since 2.0.0
+        # @api public
         def inserted_id
           inserted_ids.first
         end
 
+        # @api public
         def bulk_result
           BulkResult.new(@replies, connection_description, @inserted_ids)
         end

data/lib/mongo/operation/list_collections/result.rb

@@ -20,6 +20,7 @@ module Mongo
       # listCollections command.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # Get the cursor id for the result.
@@ -35,6 +36,7 @@ module Mongo
         # @return [ Integer ] The cursor id.
         #
         # @since 2.0.0
+        # @api private
         def cursor_id
           cursor_document ? cursor_document[CURSOR_ID] : super
         end
@@ -47,6 +49,7 @@ module Mongo
         # @return [ String ] The namespace.
         #
         # @since 2.0.0
+        # @api private
         def namespace
           cursor_document ? cursor_document[NAMESPACE] : super
         end
@@ -60,6 +63,7 @@ module Mongo
         # @return [ Array<BSON::Document> ] The documents.
         #
         # @since 2.0.0
+        # @api public
         def documents
           cursor_document[FIRST_BATCH]
         end
@@ -73,6 +77,7 @@ module Mongo
         # @return [ Result ] Self if successful.
         #
         # @since 2.0.0
+        # @api private
         def validate!
           if successful?
             self

data/lib/mongo/operation/map_reduce/result.rb

@@ -19,21 +19,25 @@ module Mongo
       # Defines custom behavior of results for a map reduce operation.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # The counts field for the map/reduce.
         #
         # @since 2.0.0
+        # @api private
         COUNTS = 'counts'.freeze
 
         # The field name for a result without a cursor.
         #
         # @since 2.0.0
+        # @api private
         RESULTS = 'results'.freeze
 
         # The time the operation took constant.
         #
         # @since 2.0.0
+        # @api private
         TIME = 'timeMillis'.freeze
 
         # Gets the map/reduce counts from the reply.
@@ -44,6 +48,7 @@ module Mongo
         # @return [ Hash ] A hash of the result counts.
         #
         # @since 2.0.0
+        # @api public
         def counts
           reply.documents[0][COUNTS]
         end
@@ -56,6 +61,7 @@ module Mongo
         # @return [ Array<BSON::Document> ] The documents.
         #
         # @since 2.0.0
+        # @api public
         def documents
           reply.documents[0][RESULTS] || reply.documents[0][RESULT]
         end
@@ -72,6 +78,7 @@ module Mongo
         # @return [ true, false ] If the command was successful.
         #
         # @since 2.0.0
+        # @api public
         def successful?
           !documents.nil?
         end
@@ -84,6 +91,7 @@ module Mongo
         # @return [ Integer ] The executing time in milliseconds.
         #
         # @since 2.0.0
+        # @api public
         def time
           reply.documents[0][TIME]
         end
@@ -102,6 +110,7 @@ module Mongo
         # @return [ Result ] The result if verification passed.
         #
         # @since 2.0.0
+        # @api private
         def validate!
           documents.nil? ? raise_operation_failure : self
         end
@@ -114,6 +123,7 @@ module Mongo
         # @return [ Integer ] Always 0 because map reduce doesn't return a cursor.
         #
         # @since 2.5.0
+        # @api private
         def cursor_id
           0
         end

data/lib/mongo/operation/parallel_scan/result.rb

@@ -19,11 +19,13 @@ module Mongo
       # Defines custom behavior of results in a parallel scan.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # The name of the cursors field in the result.
         #
         # @since 2.0.0
+        # @api private
         CURSORS = 'cursors'.freeze
 
         # Get all the cursor ids from the result.
@@ -34,6 +36,7 @@ module Mongo
         # @return [ Array<Integer> ] The cursor ids.
         #
         # @since 2.0.0
+        # @api private
         def cursor_ids
           documents.map {|doc| doc[CURSOR][CURSOR_ID]}
         end
@@ -46,6 +49,7 @@ module Mongo
         # @return [ Array<BSON::Document> ] The documents.
         #
         # @since 2.0.0
+        # @api public
         def documents
           reply.documents[0][CURSORS]
         end

data/lib/mongo/operation/result.rb

@@ -27,6 +27,7 @@ module Mongo
     # produce a reply (in which case it is assumed to have succeeded).
     #
     # @since 2.0.0
+    # @api semiprivate
     class Result
       extend Forwardable
       include Enumerable
@@ -34,41 +35,49 @@ module Mongo
       # The field name for the cursor document in an aggregation.
       #
       # @since 2.2.0
+      # @api private
       CURSOR = 'cursor'.freeze
 
       # The cursor id field in the cursor document.
       #
       # @since 2.2.0
+      # @api private
       CURSOR_ID = 'id'.freeze
 
       # The field name for the first batch of a cursor.
       #
       # @since 2.2.0
+      # @api private
       FIRST_BATCH = 'firstBatch'.freeze
 
       # The field name for the next batch of a cursor.
       #
       # @since 2.2.0
+      # @api private
       NEXT_BATCH = 'nextBatch'.freeze
 
       # The namespace field in the cursor document.
       #
       # @since 2.2.0
+      # @api private
       NAMESPACE = 'ns'.freeze
 
       # The number of documents updated in the write.
       #
       # @since 2.0.0
+      # @api private
       N = 'n'.freeze
 
       # The ok status field in the result.
       #
       # @since 2.0.0
+      # @api private
       OK = 'ok'.freeze
 
       # The result field constant.
       #
       # @since 2.2.0
+      # @api private
       RESULT = 'result'.freeze
 
       # Initialize a new result.
@@ -106,6 +115,8 @@ module Mongo
       end
 
       # @return [ Array<Protocol::Message> ] replies The wrapped wire protocol replies.
+      #
+      # @api private
       attr_reader :replies
 
       # @return [ Server::Description ] Server description of the server that
@@ -129,6 +140,7 @@ module Mongo
       # @return [ true, false ] If the result is acknowledged.
       #
       # @since 2.0.0
+      # @api public
       def acknowledged?
         !!@replies
       end
@@ -143,6 +155,7 @@ module Mongo
       # @return [ Integer ] The cursor id.
       #
       # @since 2.0.0
+      # @api private
       def cursor_id
         acknowledged? ? replies.last.cursor_id : 0
       end
@@ -153,6 +166,7 @@ module Mongo
       # @return [ Nil ]
       #
       # @since 2.0.0
+      # @api private
       def namespace
         nil
       end
@@ -165,6 +179,7 @@ module Mongo
       # @return [ Array<BSON::Document> ] The documents.
       #
       # @since 2.0.0
+      # @api public
       def documents
         if acknowledged?
           replies.flat_map(&:documents)
@@ -182,9 +197,10 @@ module Mongo
       #
       # @return [ Enumerator ] The enumerator.
       #
-      # @since 2.0.0
-      #
       # @yieldparam [ BSON::Document ] Each document in the result.
+      #
+      # @since 2.0.0
+      # @api public
       def each(&block)
         documents.each(&block)
       end
@@ -197,6 +213,7 @@ module Mongo
       # @return [ String ] The inspection.
       #
       # @since 2.0.0
+      # @api public
       def inspect
         "#<#{self.class.name}:0x#{object_id} documents=#{documents}>"
       end
@@ -209,6 +226,7 @@ module Mongo
       # @return [ Protocol::Message ] The first reply.
       #
       # @since 2.0.0
+      # @api private
       def reply
         if acknowledged?
           replies.first
@@ -225,6 +243,7 @@ module Mongo
       # @return [ Integer ] The number of documents returned.
       #
       # @since 2.0.0
+      # @api public
       def returned_count
         if acknowledged?
           reply.number_returned
@@ -245,6 +264,7 @@ module Mongo
       # @return [ true, false ] If the command was successful.
       #
       # @since 2.0.0
+      # @api public
       def successful?
         return true if !acknowledged?
         if first_document.has_key?(OK)
@@ -262,6 +282,7 @@ module Mongo
       # @return [ true, false ] If the command returned ok.
       #
       # @since 2.1.0
+      # @api public
       def ok?
         # first_document[OK] is a float, and the server can return
         # ok as a BSON int32, BSON int64 or a BSON double.
@@ -285,6 +306,7 @@ module Mongo
       # @return [ Result ] The result if verification passed.
       #
       # @since 2.0.0
+      # @api private
       def validate!
         !successful? ? raise_operation_failure : self
       end
@@ -317,12 +339,13 @@ module Mongo
       # error information in this result.
       #
       # @raise Error::OperationFailure
-      def raise_operation_failure
+      private def raise_operation_failure
         raise error
       end
-      private :raise_operation_failure
 
       # @return [ TopologyVersion | nil ] The topology version.
+      #
+      # @api private
       def topology_version
         unless defined?(@topology_version)
           @topology_version = first_document['topologyVersion'] &&
@@ -339,6 +362,7 @@ module Mongo
       # @return [ Integer ] The number of documents written.
       #
       # @since 2.0.0
+      # @api public
       def written_count
         if acknowledged?
           first_document[N] || 0
@@ -346,6 +370,8 @@ module Mongo
           0
         end
       end
+
+      # @api public
       alias :n :written_count
 
       # Get the operation time reported in the server response.
@@ -353,9 +379,10 @@ module Mongo
       # @example Get the operation time.
       #   result.operation_time
       #
-      # @return [ Object ] The operation time value.
+      # @return [ Object | nil ] The operation time value.
       #
       # @since 2.5.0
+      # @api public
       def operation_time
         first_document && first_document[OPERATION_TIME]
       end
@@ -365,13 +392,14 @@ module Mongo
       # @example Get the cluster time.
       #   result.cluster_time
       #
-      # @return [ nil | ClusterTime ] The cluster time document.
+      # @return [ ClusterTime | nil ] The cluster time document.
       #
       # Changed in version 2.9.0: This attribute became an instance of
       # ClusterTime, which is a subclass of BSON::Document.
       # Previously it was an instance of BSON::Document.
       #
       # @since 2.5.0
+      # @api public
       def cluster_time
         first_document && ClusterTime[first_document['$clusterTime']]
       end
@@ -384,6 +412,7 @@ module Mongo
       # @return [ Array ] labels The set of labels.
       #
       # @since 2.7.0
+      # @api private
       def labels
         @labels ||= parser.labels
       end