MONGOID-5640 Fix docstring issues

lib/mongoid/config/defaults.rb

@@ -11,7 +11,7 @@ module Defaults
       # Note that this method will load the *new* functionality introduced in
       # the given Mongoid version.
       #
-      # @param [ String | Float ] The version number as X.y.
+      # @param [ String | Float ] version The version number as X.y.
       #
       # raises [ ArgumentError ] if an invalid version is given.
       def load_defaults(version)

lib/mongoid/contextual/memory.rb

@@ -153,7 +153,7 @@ def first(limit = nil)
       #
       # @return [ Document ] The first document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def first!
         first || raise_document_not_found_error
@@ -214,7 +214,7 @@ def last(limit = nil)
       #
       # @return [ Document ] The last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def last!
         last || raise_document_not_found_error
@@ -312,7 +312,7 @@ def take(limit = nil)
       #
       # @return [ Document ] The document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def take!
         take || raise_document_not_found_error
@@ -373,8 +373,6 @@ def update_all(attributes = nil)
       # @example Get the second document.
       #   context.second
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The second document.
       def second
         eager_load([documents.second]).first
@@ -388,7 +386,7 @@ def second
       #
       # @return [ Document ] The second document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def second!
         second || raise_document_not_found_error
@@ -399,8 +397,6 @@ def second!
       # @example Get the third document.
       #   context.third
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The third document.
       def third
         eager_load([documents.third]).first
@@ -414,7 +410,7 @@ def third
       #
       # @return [ Document ] The third document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def third!
         third || raise_document_not_found_error
@@ -425,8 +421,6 @@ def third!
       # @example Get the fourth document.
       #   context.fourth
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The fourth document.
       def fourth
         eager_load([documents.fourth]).first
@@ -440,7 +434,7 @@ def fourth
       #
       # @return [ Document ] The fourth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def fourth!
         fourth || raise_document_not_found_error
@@ -451,8 +445,6 @@ def fourth!
       # @example Get the fifth document.
       #   context.fifth
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The fifth document.
       def fifth
         eager_load([documents.fifth]).first
@@ -466,7 +458,7 @@ def fifth
       #
       # @return [ Document ] The fifth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def fifth!
         fifth || raise_document_not_found_error
@@ -477,8 +469,6 @@ def fifth!
       # @example Get the second to last document.
       #   context.second_to_last
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The second to last document.
       def second_to_last
         eager_load([documents.second_to_last]).first
@@ -492,7 +482,7 @@ def second_to_last
       #
       # @return [ Document ] The second to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def second_to_last!
         second_to_last || raise_document_not_found_error
@@ -503,8 +493,6 @@ def second_to_last!
       # @example Get the third to last document.
       #   context.third_to_last
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The third to last document.
       def third_to_last
         eager_load([documents.third_to_last]).first
@@ -518,7 +506,7 @@ def third_to_last
       #
       # @return [ Document ] The third to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def third_to_last!
         third_to_last || raise_document_not_found_error

lib/mongoid/contextual/mongo.rb

@@ -402,7 +402,7 @@ def take(limit = nil)
       #
       # @return [ Document ] The document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def take!
         # Do to_a first so that the Mongo#first method is not used and the
@@ -584,7 +584,7 @@ def first(limit = nil)
       #
       # @return [ Document ] The first document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def first!
         first || raise_document_not_found_error
@@ -626,7 +626,7 @@ def last(limit = nil)
       #
       # @return [ Document ] The last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def last!
         last || raise_document_not_found_error
@@ -650,7 +650,7 @@ def second
       #
       # @return [ Document ] The second document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def second!
         second || raise_document_not_found_error
@@ -674,7 +674,7 @@ def third
       #
       # @return [ Document ] The third document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def third!
         third || raise_document_not_found_error
@@ -698,7 +698,7 @@ def fourth
       #
       # @return [ Document ] The fourth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def fourth!
         fourth || raise_document_not_found_error
@@ -722,7 +722,7 @@ def fifth
       #
       # @return [ Document ] The fifth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def fifth!
         fifth || raise_document_not_found_error
@@ -748,7 +748,7 @@ def second_to_last
       #
       # @return [ Document ] The second to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def second_to_last!
         second_to_last || raise_document_not_found_error
@@ -774,7 +774,7 @@ def third_to_last
       #
       # @return [ Document ] The third to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents available.
       def third_to_last!
         third_to_last || raise_document_not_found_error

lib/mongoid/contextual/mongo/documents_loader.rb

@@ -82,9 +82,9 @@ def self.executor(name = Mongoid.async_query_executor)
         # @param [ Class ] klass Mongoid model class to instantiate documents.
         #   All records obtained from the database will be converted to an
         #   instance of this class, if possible.
-        # @param [ Mongoid::Criteria ] criteria. Criteria that specifies which
+        # @param [ Mongoid::Criteria ] criteria Criteria that specifies which
         #   documents should be loaded.
-        # @param [ Concurrent::AbstractExecutorService ] executor. Executor that
+        # @param [ Concurrent::AbstractExecutorService ] executor Executor that
         #   is capable of running `Concurrent::Promises::Future` instances.
         def initialize(view, klass, criteria, executor: self.class.executor)
           @view = view

lib/mongoid/contextual/none.rb

@@ -134,7 +134,7 @@ def first(limit = nil)
       # @example Get the first document in null context.
       #   context.first!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def first!
         raise_document_not_found_error
       end
@@ -156,7 +156,7 @@ def last(limit = nil)
       # @example Get the last document in null context.
       #   context.last!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def last!
         raise_document_not_found_error
       end
@@ -178,7 +178,7 @@ def take(limit = nil)
       # @example Take a document in null context.
       #   context.take!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def take!
         raise_document_not_found_error
       end
@@ -198,7 +198,7 @@ def second
       # @example Get the second document in null context.
       #   context.second!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def second!
         raise_document_not_found_error
       end
@@ -218,7 +218,7 @@ def third
       # @example Get the third document in null context.
       #   context.third!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def third!
         raise_document_not_found_error
       end
@@ -238,7 +238,7 @@ def fourth
       # @example Get the fourth document in null context.
       #   context.fourth!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def fourth!
         raise_document_not_found_error
       end
@@ -258,7 +258,7 @@ def fifth
       # @example Get the fifth document in null context.
       #   context.fifth!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def fifth!
         raise_document_not_found_error
       end
@@ -278,7 +278,7 @@ def second_to_last
       # @example Get the second to last document in null context.
       #   context.second_to_last!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def second_to_last!
         raise_document_not_found_error
       end
@@ -298,7 +298,7 @@ def third_to_last
       # @example Get the third to last document in null context.
       #   context.third_to_last!
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      # @raise [ Mongoid::Errors::DocumentNotFound ] always raises.
       def third_to_last!
         raise_document_not_found_error
       end

lib/mongoid/criteria/queryable/storable.rb

@@ -83,7 +83,7 @@ def add_field_expression(field, value)
         #
         #     {'$or' => [{'hello' => 'world'}]}
         #
-        # ... and operator is '$or' and op_expr is `[{'test' => 123'}]`,
+        # ... and operator is '$or' and op_expr is +[{'test' => 123'}]+,
         # the resulting selector will be:
         #
         #     {'$or' => [{'hello' => 'world'}, {'test' => 123}]}
@@ -159,7 +159,7 @@ def add_logical_operator_expression(operator, op_expr)
         #
         #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
         #
-        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # ... and operator is '$or' and op_expr is +{'test' => 123'}+,
         # the resulting selector will be:
         #
         #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}

lib/mongoid/deprecation.rb

@@ -14,7 +14,7 @@ class Deprecation < ::ActiveSupport::Deprecation
     # Overrides default ActiveSupport::Deprecation behavior
     # to use Mongoid's logger.
     #
-    # @return Array<Proc> The deprecation behavior.
+    # @return [ Array<Proc> ] The deprecation behavior.
     def behavior
       @behavior ||= Array(->(message, callstack, _deprecation_horizon, _gem_name) {
         logger = Mongoid.logger

lib/mongoid/document.rb

@@ -185,7 +185,7 @@ def becomes(klass)
     # Sets the internal state of this document. Used only by #becomes to
     # help initialize a retyped document.
     #
-    # @params state [ Hash ] The map of internal state values.
+    # @param [ Hash ] state The map of internal state values.
     #
     # @api private
     def internal_state=(state)
@@ -354,7 +354,7 @@ def update_discriminator(key_was)
 
     # Marks all embedded documents with the given "new_record" state.
     #
-    # @params new_record [ true | false ] whether or not the embedded records
+    # @param [ true | false ] new_record  whether or not the embedded records
     #   should be flagged as new records or not.
     def mark_persisted_state_for_embedded_documents(new_record)
       embedded_relations.each_pair do |name, _meta|
@@ -369,7 +369,7 @@ def mark_persisted_state_for_embedded_documents(new_record)
 
     # Either executes or enqueues the post-construction callbacks.
     #
-    # @params execute_callbacks [ true | false ] whether the callbacks
+    # @param [ true | false ] execute_callbacks whether the callbacks
     #   should be executed (true) or enqueued (false)
     def resolve_post_construction_callbacks(execute_callbacks)
       if execute_callbacks
@@ -387,7 +387,7 @@ module ClassMethods
       # within the block. Callbacks may always be explicitly invoked by passing
       # `execute_callbacks: true` where available.
       #
-      # @params execute_callbacks [ true | false ] Whether callbacks should be
+      # @param [ true | false ] execute_callbacks Whether callbacks should be
       #   suppressed or not.
       def with_callbacks(execute_callbacks)
         saved, Threaded.execute_callbacks =
@@ -406,8 +406,6 @@ def with_callbacks(execute_callbacks)
       # @param [ Hash ] attrs The hash of attributes to instantiate with.
       # @param [ Integer ] selected_fields The selected fields from the
       #   criteria.
-      # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
-      #   should be run.
       #
       # @return [ Document ] A new document.
       def instantiate(attrs = nil, selected_fields = nil, &block)