MONGOID-5597 Improve documentation for Query Cache (#5598)

* Mongoid 9.0: Remove Mongoid Query Cache, replace with Mongo

* Fixes

* Update mongoid-9.0.txt

* Update mongoid-9.0.txt

Author: johnnyshields

source/reference/configuration.txt

@@ -886,13 +886,10 @@ before the workers are forked.
 Query Cache Middleware
 ======================
 
-.. note::
-
-  When used with Ruby driver version 2.15 or newer, Mongoid's Query Cache
-  Middleware delegates to `the driver's Query Cache Middleware
-  <https://www.mongodb.com/docs/ruby-driver/current/reference/query-cache/index.html#query-cache-middleware>`_.
+Enabling Query Cache for Rack Web Requests
+------------------------------------------
 
-Mongoid provides a Rack middleware which enables the :ref:`Query Cache
+The MongoDB Ruby Driver provides a Rack middleware which enables the :ref:`Query Cache
 <query-cache>` for the duration of each web request. Below is an example of
 how to enable the Query Cache Middleware in a Ruby on Rails application:
 
@@ -908,6 +905,29 @@ Please refer to the `Rails on Rack guide
 <https://guides.rubyonrails.org/rails_on_rack.html#configuring-middleware-stack>`_
 for more information about using Rack middleware in Rails applications.
 
+Enabling Query Cache for ActiveJob
+----------------------------------
+
+The MongoDB Ruby Driver also provides Query Cache middleware for ActiveJob.
+You may enable it for all jobs in an initializer:
+
+.. code-block:: ruby
+
+  # config/initializers/active_job.rb
+
+  # Enable Mongo driver query cache for ActiveJob
+  ActiveSupport.on_load(:active_job) do
+    include Mongo::QueryCache::Middleware::ActiveJob
+  end
+
+Or for a specific job class:
+
+.. code-block:: ruby
+
+  class MyJob < ActiveJob::Base
+    include Mongo::QueryCache::Middleware::ActiveJob
+  end
+
 
 Development Configuration
 =========================

source/reference/queries.txt

@@ -2344,19 +2344,17 @@ The query cache may be enabled by using the driver's namespace or Mongoid's
 namespace.
 
 
-.. _enabling-query-cache-via-middleware:
+.. _enabling-query-cache-automatically:
 
-Enabling Query Cache Via Middleware
------------------------------------
+Enabling Query Cache Automatically
+----------------------------------
 
-Applications that utilize a Rack-based web framework (Rails, etc.) can
-take advantage of the Rack middleware provided by Mongoid to automatically
-enable the query cache for each web request, and clear the query cache after
-each request completes. Please see the :ref:`Query Cache Rack Middleware
+The MongoDB Ruby Driver provides middleware to automatically enable the query cache for
+Rack web requests and ActiveJob job runs. Please see the :ref:`Query Cache Rack Middleware
 <query-cache-middleware>` section on the configuration page for instructions.
 
-Note that the Query Cache Middleware does not apply to code executed
-outside web requests.
+Note that the Query Cache Middleware does not apply to code executed outside web requests
+and/or jobs.
 
 
 .. _enabling-query-cache-manually:
@@ -2377,50 +2375,11 @@ recommend to use the block form described above:
 
 .. code-block:: ruby
 
-  Mongo::QueryCache.enabled = true
-
-  # ...
-
-  Mongo::QueryCache.enabled = false
-
-Alternatively, you can reference the driver's query cache module directly:
-
-.. code-block:: ruby
-
-  Mongo::QueryCache.cache do
+  begin
+    Mongo::QueryCache.enabled = true
     # ...
-  end
-
-  Mongo::QueryCache.enabled = true
-
-  Mongo::QueryCache.enabled = true
-
-
-Query Cache Shared With Driver
-------------------------------
-
-When Mongoid delegates to the driver's query cache, the same cache is used
-by both Mongoid and the driver. For example, the following two queries
-are implemented via the same server query and only the first of them
-would be sent to the server:
-
-.. code-block:: ruby
-
-  Mongo::QueryCache.cache do
-    Band.first
-    Band.collection.find.sort(_id: 1).first
-  end
-
-Similarly, write operations that clear the cache would do so when the read
-is performed by the driver and write by Mongoid, or vice versa:
-
-.. code-block:: ruby
-
-  Mongo::QueryCache.cache do
-    Band.first
-    Band.collection.insert_one({})
-    # Queries again
-    Band.first
+  ensure
+    Mongo::QueryCache.enabled = false
   end
 
 

source/release-notes/mongoid-9.0.txt

@@ -18,14 +18,6 @@ please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
 
-``Mongoid::QueryCache`` removed
--------------------------------
-
-The ``Mongoid::QueryCache`` module has been deprecated in Mongoid 8.1.
-It is removed in Mongoid 9.0. Please use the query cache provided by the MongoDB Ruby driver
-instead. Please review the `driver query cache documentation
-<https://mongodb.com/docs/ruby-driver/current/reference/query-cache/>`_ for more details.
-
 Deprecated options removed
 --------------------------
 
@@ -52,6 +44,15 @@ In addition, support for ``config.load_defaults`` versions 7.5 and
 prior has been dropped (you must use a minimum of version 8.0.)
 
 
+Deprecated functionality removed
+--------------------------------
+
+- The ``Mongoid::QueryCache`` module has been removed. Please replace any usages 1-for-1 with ``Mongo::QueryCache``.
+  The method ``Mongoid::QueryCache#clear_cache`` should be replaced with ``Mongo::QueryCache#clear``.
+  All other methods and submodules are identically named. Refer to the `driver query cache documentation
+  <https://mongodb.com/docs/ruby-driver/current/reference/query-cache/>`_ for more details.
+
+
 ``touch`` method now clears changed state
 -----------------------------------------