Merge remote-tracking branch 'remotes/origin/master' into evolve-rework

Author: johnnyshields

docs/contributing/code-documentation.txt

@@ -35,7 +35,7 @@ Structure
     class CardboardBox
 
 - **Methods:** All method definitions should be preceded by a documentation comment.
-  Use ``@param`` and ``@return`` to specify input(s) and output respectively.
+  Use ``@param``, ``@yield``, and ``@return`` to specify inputs and output.
   For further details, refer to
   :ref:`Type Declaration <code-documentation-type-declaration>` below.
 
@@ -48,33 +48,30 @@ Structure
     # @return [ Tiger ] The transmogrified result.
     def transmogrify(person)
 
+- **Errors:** Use ``@raise`` to explain errors specific to the method.
+
+  .. code-block:: ruby
+
+    # @raise [ Errors::Validations ] If validation failed.
+    def validate!
+
 - **Private Methods:** Private methods should be documented unless they are
   so brief and straightforward that it is obvious what they do. Note that,
   for example, a method may be brief and straightforward but the type of
-  its parameter may not be obvious, in which case the parameter needs to
-  be appropriately documented.
+  its parameter may not be obvious, in which case the parameter must be
+  appropriately documented.
 
   .. code-block:: ruby
 
     private
 
     # Documentation is optional here.
-    def my_internal_method
-
-- **Notes:** Use the ``@note`` macro to explain caveats, edge cases,
-  and behavior which may surprise users.
-
-  .. code-block:: ruby
-
-    # Clear all stored data.
-    #
-    # @note This operation deletes data in the database.
-    def erase_data!
+    def do_something_obvious
 
 - **API Private:** Classes and public methods which are not intended for
   external usage should be marked ``@api private``. This macro does not
   require a comment.
-  
+
   Note that, because Mongoid's modules are mixed into application classes,
   ``private`` visibility of a method does not necessarily indicate its
   status as an API private method.
@@ -86,6 +83,18 @@ Structure
     # @api private
     def dont_call_me_from_outside
 
+- **Notes and TODOs:** Use ``@note`` to explain caveats, edge cases,
+  and behavior which may surprise users. Use ``@todo`` to record
+  follow-ups and suggestions for future improvement.
+
+  .. code-block:: ruby
+
+    # Clear all stored data.
+    #
+    # @note This operation deletes data in the database.
+    # @todo Refactor this method for performance.
+    def erase_data!
+
 - **Deprecation:** Use the ``@deprecated`` macro to indicate deprecated
   functionality. This macro does not require a comment.
 
@@ -286,3 +295,59 @@ Type Declaration
     # @option **kwargs [ String | Array<String> ] :items The items(s) as Strings to include.
     # @option **kwargs [ Integer ] :limit An Integer denoting the limit.
     def buy_groceries(**kwargs)
+
+- **Blocks:** Use ``@yield`` to specify when the method yields to a block.
+
+  .. code-block:: ruby
+
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit
+      yield(:mustard, :ballroom, :candlestick)
+    end
+
+- **Blocks:** If the method explicitly specifies a block argument, specify the block
+  argument using ``@param`` preceded by an ampersand ``&``, and also specify ``@yield``.
+  Note ``@yield`` should be used even when method calls ``block.call`` rather than
+  ``yield`` internally.
+
+  .. code-block:: ruby
+
+    # @param &block The block.
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit(&block)
+      yield(:scarlet, :library, :rope)
+    end
+
+    # @param &block The block.
+    # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
+    #   Must take the person, location, and weapon used. Must return true or false.
+    def whodunit(&block)
+      block.call(:plum, :kitchen, :pipe)
+    end
+
+- **Blocks:** Use ``@yieldparam`` and ``@yieldreturn`` instead of ``@yield`` where
+  beneficial for clarity.
+
+  .. code-block:: ruby
+
+    # @param &block The block.
+    # @yieldparam [ Symbol ] The person.
+    # @yieldparam [ Symbol ] The location.
+    # @yieldparam [ Symbol ] The weapon used.
+    # @yieldreturn [ true | false ] Whether the guess is correct.
+    def whodunit(&block)
+      yield(:peacock, :conservatory, :wrench)
+    end
+
+- **Proc Args:** Proc arguments should use ``@param`` (not ``@yield``). The
+  inputs to the proc may be specified as subtype(s).
+
+  .. code-block:: ruby
+
+    # @param [ Proc<Integer, Integer, Integer> ] my_proc Proc argument which must
+    #   take 3 integers and must return true or false whether the guess is valid.
+    def guess_three(my_proc)
+      my_proc.call(42, 7, 88)
+    end

docs/installation.txt

@@ -27,7 +27,7 @@ To install the gem with bundler, include the following in your ``Gemfile``:
 
 .. code-block:: ruby
 
-   gem 'mongoid', '~> 7.3.0'
+   gem 'mongoid', '~> 9.0.0'
 
 Using Mongoid with a New Rails Application
 ==========================================

docs/reference/collection-configuration.txt

@@ -10,51 +10,96 @@ Collection Configuration
    :depth: 2
    :class: singlecol
 
+Configuring a Document Collection
+=================================
 
-Capped Collections
-------------------
+You can specify collection options for documents using the ``store_in`` macro.
+This macro accepts ``:collection_options`` argument, which can contain any collection
+options that are supported by the driver.
+
+.. note::
+
+  In order to apply the options, the collection must be explicitly created up-front.
+  This should be done using  :ref:`Collection Management Rake Task<collection-management-task>`.
 
-Mongoid does not provide a mechanism for creating capped collections on the fly - you
-will need to create these yourself one time up front either with the driver or via the
-Mongo console.
+Please refer to `the driver collections page
+<https://mongodb.com/docs/ruby-driver/current/reference/collection-tasks/>`_
+for the more information about collection options.
 
-To create a capped collection with the driver, first retrieve the client:
+.. note::
+
+  Collection options depend on the driver version and MongoDB server version.
+  It is possible that some options, like time series collections, are not available
+  on older server versions.
+
+Time Series Collection
+----------------------
 
 .. code-block:: ruby
 
-  class Name
+  class Measurement
     include Mongoid::Document
-  end
-  client = Name.collection.client
 
-Then create the collection:
+    field :temperature, type: Integer
+    field :timestamp, type: Time
 
-.. code-block:: ruby
+    store_in collection_options: {
+      time_series: {
+        timeField: "timestamp",
+        granularity: "minutes"
+      },
+      expire_after: 604800
+    }
+  end
 
-  client["names", :capped => true, :size => 1024].create
 
-To create a capped collection from the Mongo console:
 
-.. code-block:: javascript
+Capped Collections
+------------------
 
-  db.createCollection("name", { capped: true, size: 1024 });
+.. code-block:: ruby
 
+  class Name
+    include Mongoid::Document
+
+    store_in collection_options: {
+      capped: true,
+      size: 1024
+    }
+  end
 
 Set a Default Collation on a Collection
 ---------------------------------------
 
-Mongoid does not provide a mechanism for creating a collection with a default collation.
-Like capped collections, you will need to create the collection yourself one time, up-front,
-either with the driver or via the Mongo console.
+.. code-block:: ruby
 
-To create a collection with a default collation with the driver:
+  class Name
+    include Mongoid::Document
 
-.. code-block:: ruby
+    store_in collection_options: {
+      collation: {
+        locale: 'fr'
+      }
+    }
+  end
+
+.. _collection-management-task:
+
+Collection Management Rake Task
+===============================
 
-  client["name", :collation => { :locale => 'fr'}].create
+If you specify collection options for a document, then the corresponding collection
+must be explicitly created prior to use. To do so, use the provided
+``db:mongoid:create_collections`` Rake task:
 
-To create a collection with a default collation from the Mongo console:
+.. code-block:: bash
 
-.. code-block:: javascript
+    $ rake db:mongoid:create_collections
+
+The create collections command also works for just one model by running
+in Rails console:
+
+.. code-block:: ruby
 
-  db.createCollection("name", { collation: { locale: 'fr' } });
+    # Create collection for Model
+    Model.create_collection

docs/reference/configuration.txt

@@ -383,6 +383,17 @@ for details on driver options.
       # (default: false)
       #legacy_pluck_distinct: true
 
+      # When this flag is false, a document will become read-only only once the
+      # #readonly! method is called, and an error will be raised on attempting
+      # to save or update such documents, instead of just on delete. When this
+      # flag is true, a document is only read-only if it has been projected
+      # using #only or #without, and read-only documents will not be
+      # deletable/destroyable, but will be savable/updatable.
+      # When this feature flag is turned on, the read-only state will be reset on
+      # reload, but when it is turned off, it won't be.
+      # (default: true)
+      legacy_readonly: false
+
       # Maintain legacy behavior of === on Mongoid document classes, which
       # returns true in a number of cases where Ruby's === implementation would
       # return false. Note that the behavior of === on Mongoid document

docs/reference/crud.txt

@@ -657,7 +657,7 @@ Mongoid provides several ways of accessing field values.
 .. note::
 
   All of the access methods described below raise
-  ``ActiveModel::MissingAttributeError`` when the field being accessed is
+  ``Mongoid::Errors::AttributeNotLoaded`` when the field being accessed is
   :ref:`projected out <projection>`, either by virtue of not being included in
   :ref:`only <only>` or by virtue of being included in
   :ref:`without <without>`. This applies to both reads and writes.
@@ -974,3 +974,69 @@ back to the model as follows:
 
   band.tours
   # => #<Set: {"London"}>
+
+
+.. _readonly-documents:
+
+Readonly Documents
+==================
+
+Documents can be marked read-only in two ways, depending on the value of the
+``Mongoid.legacy_readonly`` feature flag:
+
+If this flag is turned off, a document is marked read-only when the ``#readonly!``
+method is called on that documnet. A read-only document, with this flag turned off,
+will raise a ReadonlyDocument error on attempting to perform any persistence
+operation, including (but not limited to) saving, updating, deleting and
+destroying. Note that reloading does not reset the read-only state.
+
+.. code:: ruby
+
+  band = Band.first
+  band.readonly? # => false
+  band.readonly!
+  band.readonly? # => true
+  band.name = "The Rolling Stones"
+  band.save # => raises ReadonlyDocument error
+  band.reload.readonly? # => true
+
+If this flag is turned on, a document is marked read-only when that document
+has been projected (i.e. using ``#only`` or ``#without``). A read-only document,
+with this flag turned on, will not be deletable or destroyable (a
+``ReadonlyDocument`` error will be raised), but will be saveable and updatable.
+The read-only status is reset on reloading the document.
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :genre, type: String
+  end
+
+  band = Band.only(:name).first
+  band.readonly? # => true
+  band.destroy # => raises ReadonlyDocument error
+  band.reload.readonly? # => false
+
+
+Overriding ``readonly?``
+------------------------
+
+Another way to make a document read-only is by overriding the readonly? method:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :genre, type: String
+
+    def readonly?
+      true
+    end
+  end
+
+  band = Band.first
+  band.readonly? # => true
+  band.destroy # => raises ReadonlyDocument error

docs/reference/fields.txt

@@ -1648,7 +1648,7 @@ Assignments to read-only attributes using their setters will be ignored:
   # => "The Rolling Stones"
 
 Calls to atomic persistence operators, like ``bit`` and ``inc``, will persist
-changes to readonly fields.
+changes to read-only fields.
 
 Timestamp Fields
 ================