MONGOID-5415 Use @yield syntax for blocks. Also add to documentation. (#5410)

Co-authored-by: shields <shields@tablecheck.com>

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.
 
@@ -295,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

lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -236,7 +236,8 @@ def exists?
           #   person.addresses.find { |addr| addr.state == 'CA' }
           #
           # @param [ Object... ] *args Various arguments.
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
+          # @yield [ Object ] Yields each enumerable element to the block.
           #
           # @return [ Document | Array<Document> | nil ] A document or matching documents.
           def find(*args, &block)
@@ -431,7 +432,7 @@ def integrate(document)
           #
           # @param [ Symbol | String ] name The name of the method.
           # @param [ Object... ] *args The method args.
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
           #
           # @return [ Criteria | Object ] A Criteria or return value from the target.
           ruby2_keywords def method_missing(name, *args, &block)

lib/mongoid/association/macros.rb

@@ -72,7 +72,7 @@ module ClassMethods
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -95,7 +95,7 @@ def embedded_in(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -118,7 +118,7 @@ def embeds_many(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -140,7 +140,7 @@ def embeds_one(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -162,7 +162,7 @@ def belongs_to(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -184,7 +184,7 @@ def has_many(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_and_belongs_to_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -206,7 +206,7 @@ def has_and_belongs_to_many(name, options = {}, &block)
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end

lib/mongoid/association/referenced/has_many/proxy.rb

@@ -200,7 +200,8 @@ def exists?
           #   later.
           #
           # @param [ [ Object | Array<Object> ]... ] *args The ids.
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
+          # @yield [ Object ] Yields each enumerable element to the block.
           #
           # @return [ Document | Array<Document> | nil ] A document or matching documents.
           def find(*args, &block)
@@ -415,7 +416,7 @@ def cascade!(document)
           #
           # @param [ Symbol | String ] name The name of the method.
           # @param [ Object... ] *args The method args
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
           #
           # @return [ Criteria | Object ] A Criteria or return value from the target.
           ruby2_keywords def method_missing(name, *args, &block)

lib/mongoid/criteria.rb

@@ -89,7 +89,8 @@ def ==(other)
     #   enumerator = criteria.find(-> { "Default Band" })
     #
     # @param [ [ Object | Array<Object> ]... ] *args The id(s).
-    # @param [ Proc ] block Optional block to pass.
+    # @param &block Optional block to pass.
+    # @yield [ Object ] Yields each enumerable element to the block.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #

lib/mongoid/extensions/module.rb

@@ -13,7 +13,7 @@ module Module
       #   end
       #
       # @param [ String | Symbol ] name The name of the method.
-      # @param [ Proc ] block The method body.
+      # @param &block The method body.
       #
       # @return [ Method ] The new method.
       def re_define_method(name, &block)

lib/mongoid/fields.rb

@@ -287,8 +287,7 @@ class << self
       #   end
       #
       # @param [ Symbol ] option_name the option name to match against
-      # @param [ Proc ] block the handler to execute when the option is
-      #   provided.
+      # @param &block the handler to execute when the option is provided.
       def option(option_name, &block)
         options[option_name] = block
       end
@@ -320,8 +319,10 @@ def options
       # @param [ Hash ] associations The associations to begin the search with.
       # @param [ Hash ] aliased_associations The alaised associations to begin
       #   the search with.
-      # @param [ Proc ] block The block takes in three paramaters, the current
-      #   meth, the field or the relation, and whether the second parameter is a
+      # @param &block The block.
+      # @yieldparam [ Symbol ] The current method.
+      # @yieldparam [ Symbol | String ] The field or the relation.
+      # @yieldparam [ true | false ] Whether the second yield parameter is a
       #   field or not.
       #
       # @return [ Field ] The field found for the given key at the end of the
@@ -516,8 +517,10 @@ def using_object_ids?
       # given key.
       #
       # @param [ String ] key The key used to search the association tree.
-      # @param [ Proc ] block The block takes in three paramaters, the current
-      #   meth, the field or the relation, and whether the second parameter is a
+      # @param &block The block.
+      # @yieldparam [ Symbol ] The current method.
+      # @yieldparam [ Symbol | String ] The field or the relation.
+      # @yieldparam [ true | false ] Whether the second yield parameter is a
       #   field or not.
       #
       # @return [ Field ] The field found for the given key at the end of the