[READY FOR REVIEW] MONGOID-5720 - Deprecate GeoNear class and Criteria#max_scan methods

docs/release-notes/mongoid-9.0.txt

@@ -594,3 +594,17 @@ This section will be for smaller bug fixes and improvements:
 - Added support for serializing and deserializing BSON::ObjectId values
   when passed as ActiveJob arguments
   `MONGOID-5611 <https://jira.mongodb.org/browse/MONGOID-5611>`_.
+
+
+Newly deprecated functionality
+------------------------------
+
+The following functionality is deprecated and will be removed in a future
+Mongoid major version release:
+
+- The ``GeoNear`` class, which was `removed in MongoDB Server 4.2
+  <https://www.mongodb.com/docs/manual/release-notes/4.2-compatibility/#remove-support-for-the-geonear-command>`_.
+  Use the $geoNear aggregation pipeline stage instead.
+- The ``Criteria#max_scan` method, which was `removed in MongoDB Server 4.2
+  <https://www.mongodb.com/docs/manual/release-notes/4.2-compatibility/#remove-maxscan>`_.
+  Use the ``Criteria#max_time_ms`` method instead.

lib/mongoid/contextual/geo_near.rb

@@ -5,6 +5,9 @@ module Mongoid
   module Contextual
 
     # Represents a $geoNear database command instruction.
+    #
+    # @deprecated GeoNear is removed as of MongoDB Server 4.2. Please use the
+    #   $geoNear aggregation pipeline stage instead.
     class GeoNear
       extend Forwardable
       include Enumerable
@@ -20,6 +23,8 @@ class GeoNear
       #   geo_near.average_distance
       #
       # @return [ Float | nil ] The average distance.
+      #
+      # @deprecated
       def average_distance
         average = stats["avgDistance"]
         (average.nil? || average.nan?) ? nil : average
@@ -34,6 +39,8 @@ def average_distance
       #   end
       #
       # @return [ Enumerator ] The enumerator.
+      #
+      # @deprecated
       def each
         if block_given?
           documents.each do |doc|
@@ -52,6 +59,8 @@ def each
       # @param [ Integer | Float ] value The distance multiplier.
       #
       # @return [ GeoNear ] The GeoNear wrapper.
+      #
+      # @deprecated
       def distance_multiplier(value)
         command[:distanceMultiplier] = value
         self
@@ -66,6 +75,8 @@ def distance_multiplier(value)
       #   operation on.
       # @param [ Criteria ] criteria The Mongoid criteria.
       # @param [ String ] near
+      #
+      # @deprecated
       def initialize(collection, criteria, near)
         @collection, @criteria = collection, criteria
         command[:geoNear] = collection.name.to_s
@@ -79,6 +90,8 @@ def initialize(collection, criteria, near)
       #   geo_near.inspect
       #
       # @return [ String ] The inspection string.
+      #
+      # @deprecated
       def inspect
 %Q{#<Mongoid::Contextual::GeoNear
   selector:   #{criteria.selector.inspect}
@@ -104,6 +117,8 @@ def inspect
       # @param [ Integer | Float ] value The maximum distance.
       #
       # @return [ GeoNear | Float ] The GeoNear command or the value.
+      #
+      # @deprecated
       def max_distance(value = nil)
         if value
           command[:maxDistance] = value
@@ -121,6 +136,8 @@ def max_distance(value = nil)
       # @param [ Integer | Float ] value The minimum distance.
       #
       # @return [ GeoNear ] The GeoNear command.
+      #
+      # @deprecated
       def min_distance(value)
         command[:minDistance] = value
         self
@@ -132,6 +149,8 @@ def min_distance(value)
       #   geo_near.spherical
       #
       # @return [ GeoNear ] The command.
+      #
+      # @deprecated
       def spherical
         command[:spherical] = true
         self
@@ -145,6 +164,8 @@ def spherical
       # @param [ true | false ] value Whether to return unique documents.
       #
       # @return [ GeoNear ] The command.
+      #
+      # @deprecated
       def unique(value = true)
         command[:unique] = value
         self
@@ -156,6 +177,8 @@ def unique(value = true)
       #   geo_near.execute
       #
       # @return [ Hash ] The raw output
+      #
+      # @deprecated
       def execute
         results
       end
@@ -166,6 +189,8 @@ def execute
       #   geo_near.stats
       #
       # @return [ Hash ] The stats from the command run.
+      #
+      # @deprecated
       def stats
         results["stats"]
       end
@@ -176,6 +201,8 @@ def stats
       #   geo_near.time
       #
       # @return [ Float ] The execution time.
+      #
+      # @deprecated
       def time
         stats["time"]
       end
@@ -186,6 +213,8 @@ def time
       #   geo_near.empty_and_chainable?
       #
       # @return [ true ] Always true.
+      #
+      # @deprecated
       def empty_and_chainable?
         true
       end

lib/mongoid/criteria/queryable/optional.rb

@@ -93,6 +93,8 @@ def limit(value = nil)
         # @param [ Integer ] value The max number of documents to scan.
         #
         # @return [ Optional ] The cloned optional.
+        #
+        # @deprecated max_scan is removed as of MongoDB Server 4.2. Please use max_time_ms instead.
         def max_scan(value = nil)
           option(value) { |options| options.store(:max_scan, value) }
         end