Merge pull request #26905 from bogdanvlviv/docs

Add missing `+` around a some literals.

42 files changed, 77 insertions, 75 deletions

diff --git a/actionpack/lib/abstract_controller/base.rb b/actionpack/lib/abstract_controller/base.rb
index 8e588812f8..603c2e9ea7 100644
--- a/actionpack/lib/abstract_controller/base.rb
+++ b/actionpack/lib/abstract_controller/base.rb
@@ -215,7 +215,7 @@ module AbstractController
       # ==== Returns
       # * <tt>string</tt> - The name of the method that handles the action
       # * false           - No valid method name could be found.
-      # Raise AbstractController::ActionNotFound.
+      # Raise +AbstractController::ActionNotFound+.
       def _find_action_name(action_name)
         _valid_action_name?(action_name) && method_for_action(action_name)
       end
@@ -231,11 +231,11 @@ module AbstractController
       # with a template matching the action name is considered to exist.
       #
       # If you override this method to handle additional cases, you may
-      # also provide a method (like _handle_method_missing) to handle
+      # also provide a method (like +_handle_method_missing+) to handle
       # the case.
       #
-      # If none of these conditions are true, and method_for_action
-      # returns nil, an AbstractController::ActionNotFound exception will be raised.
+      # If none of these conditions are true, and +method_for_action+
+      # returns +nil+, an +AbstractController::ActionNotFound+ exception will be raised.
       #
       # ==== Parameters
       # * <tt>action_name</tt> - An action name to find a method name for
diff --git a/actionpack/lib/action_controller/metal/etag_with_template_digest.rb b/actionpack/lib/action_controller/metal/etag_with_template_digest.rb
index 6c103bb042..798564db96 100644
--- a/actionpack/lib/action_controller/metal/etag_with_template_digest.rb
+++ b/actionpack/lib/action_controller/metal/etag_with_template_digest.rb
@@ -40,7 +40,7 @@ module ActionController
       end
 
       # Pick the template digest to include in the ETag. If the +:template+ option
-      # is present, use the named template. If +:template+ is nil or absent, use
+      # is present, use the named template. If +:template+ is +nil+ or absent, use
       # the default controller/action template. If +:template+ is false, omit the
       # template digest from the ETag.
       def pick_template_for_etag(options)
diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index 49c9dc90f1..e14da22e01 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -549,7 +549,7 @@ module ActionController
       new_instance_with_inherited_permitted_status(@parameters.select(&block))
     end
 
-    # Equivalent to Hash#keep_if, but returns nil if no changes were made.
+    # Equivalent to Hash#keep_if, but returns +nil+ if no changes were made.
     def select!(&block)
       @parameters.select!(&block)
       self
diff --git a/actionpack/lib/action_dispatch/http/response.rb b/actionpack/lib/action_dispatch/http/response.rb
index 803ac52605..357ca56036 100644
--- a/actionpack/lib/action_dispatch/http/response.rb
+++ b/actionpack/lib/action_dispatch/http/response.rb
@@ -249,7 +249,7 @@ module ActionDispatch # :nodoc:
       end
     end
 
-    # Sets the HTTP character set. In case of nil parameter
+    # Sets the HTTP character set. In case of +nil+ parameter
     # it sets the charset to utf-8.
     #
     #   response.charset = 'utf-16' # => 'utf-16'
diff --git a/actionpack/lib/action_dispatch/middleware/cookies.rb b/actionpack/lib/action_dispatch/middleware/cookies.rb
index 4fc4df4463..956c53e813 100644
--- a/actionpack/lib/action_dispatch/middleware/cookies.rb
+++ b/actionpack/lib/action_dispatch/middleware/cookies.rb
@@ -179,7 +179,7 @@ module ActionDispatch
 
       # Returns a jar that'll automatically generate a signed representation of cookie value and verify it when reading from
       # the cookie again. This is useful for creating cookies with values that the user is not supposed to change. If a signed
-      # cookie was tampered with by the user (or a 3rd party), nil will be returned.
+      # cookie was tampered with by the user (or a 3rd party), +nil+ will be returned.
       #
       # If +secrets.secret_key_base+ and +secrets.secret_token+ (deprecated) are both set,
       # legacy cookies signed with the old key generator will be transparently upgraded.
@@ -202,7 +202,7 @@ module ActionDispatch
       end
 
       # Returns a jar that'll automatically encrypt cookie values before sending them to the client and will decrypt them for read.
-      # If the cookie was tampered with by the user (or a 3rd party), nil will be returned.
+      # If the cookie was tampered with by the user (or a 3rd party), +nil+ will be returned.
       #
       # If +secrets.secret_key_base+ and +secrets.secret_token+ (deprecated) are both set,
       # legacy cookies signed with the old key generator will be transparently upgraded.
diff --git a/actionpack/lib/action_dispatch/middleware/flash.rb b/actionpack/lib/action_dispatch/middleware/flash.rb
index 6900934712..6dddcc6ee1 100644
--- a/actionpack/lib/action_dispatch/middleware/flash.rb
+++ b/actionpack/lib/action_dispatch/middleware/flash.rb
@@ -129,7 +129,7 @@ module ActionDispatch
       end
 
       # Builds a hash containing the flashes to keep for the next request.
-      # If there are none to keep, returns nil.
+      # If there are none to keep, returns +nil+.
       def to_session_value #:nodoc:
         flashes_to_keep = @flashes.except(*@discard)
         return nil if flashes_to_keep.empty?
diff --git a/actionpack/lib/action_dispatch/request/session.rb b/actionpack/lib/action_dispatch/request/session.rb
index 8b98009efc..a2a80f39fc 100644
--- a/actionpack/lib/action_dispatch/request/session.rb
+++ b/actionpack/lib/action_dispatch/request/session.rb
@@ -85,7 +85,7 @@ module ActionDispatch
       end
 
       # Returns value of the key stored in the session or
-      # nil if the given key is not found in the session.
+      # +nil+ if the given key is not found in the session.
       def [](key)
         load_for_read!
         @delegate[key.to_s]
diff --git a/actionview/lib/action_view/helpers/asset_url_helper.rb b/actionview/lib/action_view/helpers/asset_url_helper.rb
index fab49e402b..a089502dd9 100644
--- a/actionview/lib/action_view/helpers/asset_url_helper.rb
+++ b/actionview/lib/action_view/helpers/asset_url_helper.rb
@@ -97,7 +97,7 @@ module ActionView
     # to avoid warnings in the client about mixed media.
     # Note that the request parameter might not be supplied, e.g. when the assets
     # are precompiled via a Rake task. Make sure to use a Proc instead of a lambda,
-    # since a Proc allows missing parameters and sets them to nil.
+    # since a +Proc+ allows missing parameters and sets them to +nil+.
     #
     #   config.action_controller.asset_host = Proc.new { |source, request|
     #     if request && request.ssl?
@@ -232,7 +232,7 @@ module ActionView
         stylesheet: ".css"
       }
 
-      # Compute extname to append to asset path. Returns nil if
+      # Compute extname to append to asset path. Returns +nil+ if
       # nothing should be added.
       def compute_asset_extname(source, options = {})
         return if options[:extname] == false
diff --git a/actionview/lib/action_view/helpers/atom_feed_helper.rb b/actionview/lib/action_view/helpers/atom_feed_helper.rb
index cef8098f67..3538515aee 100644
--- a/actionview/lib/action_view/helpers/atom_feed_helper.rb
+++ b/actionview/lib/action_view/helpers/atom_feed_helper.rb
@@ -163,7 +163,7 @@ module ActionView
           @xml, @view, @feed_options = xml, view, feed_options
         end
 
-        # Accepts a Date or Time object and inserts it in the proper format. If nil is passed, current time in UTC is used.
+        # Accepts a Date or Time object and inserts it in the proper format. If +nil+ is passed, current time in UTC is used.
         def updated(date_or_time = nil)
           @xml.updated((date_or_time || Time.now.utc).xmlschema)
         end
@@ -174,7 +174,7 @@ module ActionView
         #
         # * <tt>:published</tt>: Time first published. Defaults to the created_at attribute on the record if one such exists.
         # * <tt>:updated</tt>: Time of update. Defaults to the updated_at attribute on the record if one such exists.
-        # * <tt>:url</tt>: The URL for this entry or false or nil for not having a link tag. Defaults to the polymorphic_url for the record.
+        # * <tt>:url</tt>: The URL for this entry or +false+ or +nil+ for not having a link tag. Defaults to the +polymorphic_url+ for the record.
         # * <tt>:id</tt>: The ID for this entry. Defaults to "tag:#{@view.request.host},#{@feed_options[:schema_date]}:#{record.class}/#{record.id}"
         # * <tt>:type</tt>: The TYPE for this entry. Defaults to "text/html".
         def entry(record, options = {})
diff --git a/actionview/lib/action_view/helpers/date_helper.rb b/actionview/lib/action_view/helpers/date_helper.rb
index 8ec351b360..09dc6ef6bd 100644
--- a/actionview/lib/action_view/helpers/date_helper.rb
+++ b/actionview/lib/action_view/helpers/date_helper.rb
@@ -220,7 +220,7 @@ module ActionView
       #   the respective locale (e.g. [:year, :month, :day] in the en locale that ships with Rails).
       # * <tt>:include_blank</tt>     - Include a blank option in every select field so it's possible to set empty
       #   dates.
-      # * <tt>:default</tt>           - Set a default date if the affected date isn't set or is nil.
+      # * <tt>:default</tt>           - Set a default date if the affected date isn't set or is +nil+.
       # * <tt>:selected</tt>          - Set a date that overrides the actual value.
       # * <tt>:disabled</tt>          - Set to true if you want show the select fields as disabled.
       # * <tt>:prompt</tt>            - Set to true (for a generic prompt), a prompt string or a hash of prompt strings
@@ -866,7 +866,7 @@ module ActionView
         end
 
         # Returns translated month names, but also ensures that a custom month
-        # name array has a leading nil element.
+        # name array has a leading +nil+ element.
         def month_names
           @month_names ||= begin
             month_names = @options[:use_month_names] || translated_month_names
diff --git a/actionview/lib/action_view/helpers/text_helper.rb b/actionview/lib/action_view/helpers/text_helper.rb
index bd3371ccc8..07dccf5b41 100644
--- a/actionview/lib/action_view/helpers/text_helper.rb
+++ b/actionview/lib/action_view/helpers/text_helper.rb
@@ -151,7 +151,7 @@ module ActionView
       # defined in <tt>:radius</tt> (which defaults to 100). If the excerpt radius overflows the beginning or end of the +text+,
       # then the <tt>:omission</tt> option (which defaults to "...") will be prepended/appended accordingly. Use the
       # <tt>:separator</tt> option to choose the delimitation. The resulting string will be stripped in any case. If the +phrase+
-      # isn't found, nil is returned.
+      # isn't found, +nil+ is returned.
       #
       #   excerpt('This is an example', 'an', radius: 5)
       #   # => ...s is an exam...
diff --git a/actionview/lib/action_view/layouts.rb b/actionview/lib/action_view/layouts.rb
index e8abfeac52..bb1d3032ad 100644
--- a/actionview/lib/action_view/layouts.rb
+++ b/actionview/lib/action_view/layouts.rb
@@ -91,16 +91,16 @@ module ActionView
   #     layout false
   #
   # In these examples, we have three implicit lookup scenarios:
-  # * The BankController uses the "bank" layout.
-  # * The ExchangeController uses the "exchange" layout.
-  # * The CurrencyController inherits the layout from BankController.
+  # * The +BankController+ uses the "bank" layout.
+  # * The +ExchangeController+ uses the "exchange" layout.
+  # * The +CurrencyController+ inherits the layout from BankController.
   #
   # However, when a layout is explicitly set, the explicitly set layout wins:
-  # * The InformationController uses the "information" layout, explicitly set.
-  # * The TellerController also uses the "information" layout, because the parent explicitly set it.
-  # * The EmployeeController uses the "employee" layout, because it set the layout to nil, resetting the parent configuration.
-  # * The VaultController chooses a layout dynamically by calling the <tt>access_level_layout</tt> method.
-  # * The TillController does not use a layout at all.
+  # * The +InformationController+ uses the "information" layout, explicitly set.
+  # * The +TellerController+ also uses the "information" layout, because the parent explicitly set it.
+  # * The +EmployeeController+ uses the "employee" layout, because it set the layout to +nil+, resetting the parent configuration.
+  # * The +VaultController+ chooses a layout dynamically by calling the <tt>access_level_layout</tt> method.
+  # * The +TillController+ does not use a layout at all.
   #
   # == Types of layouts
   #
@@ -148,8 +148,8 @@ module ActionView
   # The template will be looked always in <tt>app/views/layouts/</tt> folder. But you can point
   # <tt>layouts</tt> folder direct also. <tt>layout "layouts/demo"</tt> is the same as <tt>layout "demo"</tt>.
   #
-  # Setting the layout to nil forces it to be looked up in the filesystem and fallbacks to the parent behavior if none exists.
-  # Setting it to nil is useful to re-enable template lookup overriding a previous configuration set in the parent:
+  # Setting the layout to +nil+ forces it to be looked up in the filesystem and fallbacks to the parent behavior if none exists.
+  # Setting it to +nil+ is useful to re-enable template lookup overriding a previous configuration set in the parent:
   #
   #     class ApplicationController < ActionController::Base
   #       layout "application"
@@ -254,7 +254,7 @@ module ActionView
       # true::   raise an ArgumentError
       # nil::    Force default layout behavior with inheritance
       #
-      # Return value of Proc & Symbol arguments should be String, false, true or nil
+      # Return value of +Proc & Symbol+ arguments should be +String+, +false+, +true+ or +nil+
       # with the same meaning as described above.
       # ==== Parameters
       # * <tt>layout</tt> - The layout to use.
@@ -404,11 +404,11 @@ module ActionView
     #
     # ==== Parameters
     # * <tt>formats</tt> - The formats accepted to this layout
-    # * <tt>require_layout</tt> - If set to true and layout is not found,
-    #   an +ArgumentError+ exception is raised (defaults to false)
+    # * <tt>require_layout</tt> - If set to +true+ and layout is not found,
+    #   an +ArgumentError+ exception is raised (defaults to +false+)
     #
     # ==== Returns
-    # * <tt>template</tt> - The template object for the default layout (or nil)
+    # * <tt>template</tt> - The template object for the default layout (or +nil+)
     def _default_layout(formats, require_layout = false)
       begin
         value = _layout(formats) if action_has_layout?
diff --git a/actionview/lib/action_view/renderer/partial_renderer.rb b/actionview/lib/action_view/renderer/partial_renderer.rb
index bf338ec910..b8a79da97f 100644
--- a/actionview/lib/action_view/renderer/partial_renderer.rb
+++ b/actionview/lib/action_view/renderer/partial_renderer.rb
@@ -98,7 +98,7 @@ module ActionView
   #
   #   <%= render partial: "ad", collection: @advertisements, spacer_template: "ad_divider" %>
   #
-  # If the given <tt>:collection</tt> is nil or empty, <tt>render</tt> will return nil. This will allow you
+  # If the given <tt>:collection</tt> is +nil+ or empty, <tt>render</tt> will return nil. This will allow you
   # to specify a text which will displayed instead by using this form:
   #
   #   <%= render(partial: "ad", collection: @advertisements) || "There's no ad to be displayed" %>
diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb
index 8b815155b1..a1f7c971db 100644
--- a/activemodel/lib/active_model/validations.rb
+++ b/activemodel/lib/active_model/validations.rb
@@ -68,7 +68,7 @@ module ActiveModel
       #
       # Options:
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
@@ -134,7 +134,7 @@ module ActiveModel
       #
       # Options:
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
diff --git a/activemodel/lib/active_model/validations/validates.rb b/activemodel/lib/active_model/validations/validates.rb
index c3cbb6e291..f95f44de61 100644
--- a/activemodel/lib/active_model/validations/validates.rb
+++ b/activemodel/lib/active_model/validations/validates.rb
@@ -72,7 +72,7 @@ module ActiveModel
       # There is also a list of options that could be used along with validators:
       #
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
diff --git a/activemodel/lib/active_model/validations/with.rb b/activemodel/lib/active_model/validations/with.rb
index 6ae9630d82..e3f7a9bcb2 100644
--- a/activemodel/lib/active_model/validations/with.rb
+++ b/activemodel/lib/active_model/validations/with.rb
@@ -45,7 +45,7 @@ module ActiveModel
       #
       # Configuration options:
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
diff --git a/activerecord/lib/active_record/aggregations.rb b/activerecord/lib/active_record/aggregations.rb
index 5ca8fe576e..08dfc3a64f 100644
--- a/activerecord/lib/active_record/aggregations.rb
+++ b/activerecord/lib/active_record/aggregations.rb
@@ -206,7 +206,7 @@ module ActiveRecord
         #   or a Proc that is called when a new value is assigned to the value object. The converter is
         #   passed the single value that is used in the assignment and is only called if the new value is
         #   not an instance of <tt>:class_name</tt>. If <tt>:allow_nil</tt> is set to true, the converter
-        #   can return nil to skip the assignment.
+        #   can return +nil+ to skip the assignment.
         #
         # Option examples:
         #   composed_of :temperature, mapping: %w(reading celsius)
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index b5f1f1980a..3c94c4bd7f 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -264,7 +264,7 @@ module ActiveRecord
         super
       end
 
-      # Returns the specified association instance if it exists, nil otherwise.
+      # Returns the specified association instance if it exists, +nil+ otherwise.
       def association_instance_get(name)
         @association_cache[name]
       end
diff --git a/activerecord/lib/active_record/associations/association.rb b/activerecord/lib/active_record/associations/association.rb
index bbf3561916..84d0493a60 100644
--- a/activerecord/lib/active_record/associations/association.rb
+++ b/activerecord/lib/active_record/associations/association.rb
@@ -263,7 +263,7 @@ module ActiveRecord
         # so that when stale_state is different from the value stored on the last find_target,
         # the target is stale.
         #
-        # This is only relevant to certain associations, which is why it returns nil by default.
+        # This is only relevant to certain associations, which is why it returns +nil+ by default.
         def stale_state
         end
 
diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb
index f8aac895d7..5a323c62e6 100644
--- a/activerecord/lib/active_record/associations/collection_association.rb
+++ b/activerecord/lib/active_record/associations/collection_association.rb
@@ -428,8 +428,9 @@ module ActiveRecord
           records.each { |record| callback(:after_remove, record) }
         end
 
-        # Delete the given records from the association, using one of the methods :destroy,
-        # :delete_all or :nullify (or nil, in which case a default is used).
+        # Delete the given records from the association,
+        # using one of the methods +:destroy+, +:delete_all+
+        # or +:nullify+ (or +nil+, in which case a default is used).
         def delete_records(records, method)
           raise NotImplementedError
         end
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
index 5d8546916e..e6b6b60c1b 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
@@ -69,7 +69,7 @@ module ActiveRecord
     #   threads, which can occur if a programmer forgets to close a
     #   connection at the end of a thread or a thread dies unexpectedly.
     #   Regardless of this setting, the Reaper will be invoked before every
-    #   blocking wait. (Default nil, which means don't schedule the Reaper).
+    #   blocking wait. (Default +nil+, which means don't schedule the Reaper).
     #
     #--
     # Synchronization policy:
@@ -116,7 +116,7 @@ module ActiveRecord
           end
         end
 
-        # If +element+ is in the queue, remove and return it, or nil.
+        # If +element+ is in the queue, remove and return it, or +nil+.
         def delete(element)
           synchronize do
             @queue.delete(element)
@@ -135,7 +135,7 @@ module ActiveRecord
         # If +timeout+ is not given, remove and return the head the
         # queue if the number of available elements is strictly
         # greater than the number of threads currently waiting (that
-        # is, don't jump ahead in line).  Otherwise, return nil.
+        # is, don't jump ahead in line).  Otherwise, return +nil+.
         #
         # If +timeout+ is given, block if there is no element
         # available, waiting up to +timeout+ seconds for an element to
@@ -171,14 +171,14 @@ module ActiveRecord
             @queue.size > @num_waiting
           end
 
-          # Removes and returns the head of the queue if possible, or nil.
+          # Removes and returns the head of the queue if possible, or +nil+.
           def remove
             @queue.shift
           end
 
           # Remove and return the head the queue if the number of
           # available elements is strictly greater than the number of
-          # threads currently waiting.  Otherwise, return nil.
+          # threads currently waiting.  Otherwise, return +nil+.
           def no_wait_poll
             remove if can_remove_no_wait?
           end
@@ -282,7 +282,7 @@ module ActiveRecord
       end
 
       # Every +frequency+ seconds, the reaper will call +reap+ on +pool+.
-      # A reaper instantiated with a nil frequency will never reap the
+      # A reaper instantiated with a +nil+ frequency will never reap the
       # connection pool.
       #
       # Configure the frequency by setting "reaping_frequency" in your
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
index 95c72f1e20..407e019326 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
@@ -46,7 +46,7 @@ module ActiveRecord
       end
 
       # Returns the maximum number of elements in an IN (x,y,z) clause.
-      # nil means no limit.
+      # +nil+ means no limit.
       def in_clause_length
         nil
       end
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
index aa2dfdd573..faccd1d641 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
@@ -115,7 +115,7 @@ module ActiveRecord
 
       # Executes an INSERT query and returns the new record's ID
       #
-      # +id_value+ will be returned unless the value is nil, in
+      # +id_value+ will be returned unless the value is +nil+, in
       # which case the database will attempt to calculate the last inserted
       # id and return that value.
       #
diff --git a/activerecord/lib/active_record/connection_adapters/postgresql/utils.rb b/activerecord/lib/active_record/connection_adapters/postgresql/utils.rb
index 9a0b80d7d3..1412928ca5 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql/utils.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql/utils.rb
@@ -53,7 +53,7 @@ module ActiveRecord
 
         # Returns an instance of <tt>ActiveRecord::ConnectionAdapters::PostgreSQL::Name</tt>
         # extracted from +string+.
-        # +schema+ is nil if not specified in +string+.
+        # +schema+ is +nil+ if not specified in +string+.
         # +schema+ and +identifier+ exclude surrounding quotes (regardless of whether provided in +string+)
         # +string+ supports the range of schema/table references understood by PostgreSQL, for example:
         #
diff --git a/activerecord/lib/active_record/errors.rb b/activerecord/lib/active_record/errors.rb
index 8fbe43e3ec..6464d40c94 100644
--- a/activerecord/lib/active_record/errors.rb
+++ b/activerecord/lib/active_record/errors.rb
@@ -43,7 +43,7 @@ module ActiveRecord
 
   # Raised when connection to the database could not been established (for example when
   # {ActiveRecord::Base.connection=}[rdoc-ref:ConnectionHandling#connection]
-  # is given a nil object).
+  # is given a +nil+ object).
   class ConnectionNotEstablished < ActiveRecordError
   end
 
diff --git a/activerecord/lib/active_record/integration.rb b/activerecord/lib/active_record/integration.rb
index 3c54c6048d..8e71b60b29 100644
--- a/activerecord/lib/active_record/integration.rb
+++ b/activerecord/lib/active_record/integration.rb
@@ -15,9 +15,9 @@ module ActiveRecord
       self.cache_timestamp_format = :usec
     end
 
-    # Returns a String, which Action Pack uses for constructing a URL to this
-    # object. The default implementation returns this record's id as a String,
-    # or nil if this record's unsaved.
+    # Returns a +String+, which Action Pack uses for constructing a URL to this
+    # object. The default implementation returns this record's id as a +String+,
+    # or +nil+ if this record's unsaved.
     #
     # For example, suppose that you have a User model, and that you have a
     # <tt>resources :users</tt> route. Normally, +user_path+ will
diff --git a/activerecord/lib/active_record/model_schema.rb b/activerecord/lib/active_record/model_schema.rb
index 525f7444a5..2a28c6bf6d 100644
--- a/activerecord/lib/active_record/model_schema.rb
+++ b/activerecord/lib/active_record/model_schema.rb
@@ -292,7 +292,7 @@ module ActiveRecord
       end
 
       # Sets the name of the sequence to use when generating ids to the given
-      # value, or (if the value is nil or false) to the value returned by the
+      # value, or (if the value is +nil+ or +false+) to the value returned by the
       # given block. This is required for Oracle and is useful for any
       # database which relies on sequences for primary key generation.
       #
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 147685e32c..ef3c3bfae8 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -536,7 +536,7 @@ module ActiveRecord
 
         # Attempts to find the inverse association name automatically.
         # If it cannot find a suitable inverse association name, it returns
-        # nil.
+        # +nil+.
         def inverse_name
           options.fetch(:inverse_of) do
             @automatic_inverse_of ||= automatic_inverse_of
diff --git a/activerecord/lib/active_record/scoping/named.rb b/activerecord/lib/active_record/scoping/named.rb
index 094c0e9c6f..6af84c1266 100644
--- a/activerecord/lib/active_record/scoping/named.rb
+++ b/activerecord/lib/active_record/scoping/named.rb
@@ -42,7 +42,7 @@ module ActiveRecord
         # Adds a class method for retrieving and querying objects.
         # The method is intended to return an ActiveRecord::Relation
         # object, which is composable with other scopes.
-        # If it returns nil or false, an
+        # If it returns +nil+ or +false+, an
         # {all}[rdoc-ref:Scoping::Named::ClassMethods#all] scope is returned instead.
         #
         # A \scope represents a narrowing of a database query, such as
diff --git a/activerecord/lib/active_record/validations/associated.rb b/activerecord/lib/active_record/validations/associated.rb
index b14db85167..c695965d7b 100644
--- a/activerecord/lib/active_record/validations/associated.rb
+++ b/activerecord/lib/active_record/validations/associated.rb
@@ -37,7 +37,7 @@ module ActiveRecord
       #
       # * <tt>:message</tt> - A custom error message (default is: "is invalid").
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
diff --git a/activerecord/lib/active_record/validations/presence.rb b/activerecord/lib/active_record/validations/presence.rb
index ad82ea66c4..ca5eda2f84 100644
--- a/activerecord/lib/active_record/validations/presence.rb
+++ b/activerecord/lib/active_record/validations/presence.rb
@@ -44,7 +44,7 @@ module ActiveRecord
       # Configuration options:
       # * <tt>:message</tt> - A custom error message (default is: "can't be blank").
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
-      #   Runs in all validation contexts by default (nil). You can pass a symbol
+      #   Runs in all validation contexts by default +nil+. You can pass a symbol
       #   or an array of symbols. (e.g. <tt>on: :create</tt> or
       #   <tt>on: :custom_validation_context</tt> or
       #   <tt>on: [:create, :custom_validation_context]</tt>)
diff --git a/activesupport/lib/active_support/core_ext/hash/compact.rb b/activesupport/lib/active_support/core_ext/hash/compact.rb
index 5cae495bda..e357284be0 100644
--- a/activesupport/lib/active_support/core_ext/hash/compact.rb
+++ b/activesupport/lib/active_support/core_ext/hash/compact.rb
@@ -14,7 +14,7 @@ class Hash
 
   unless Hash.instance_methods(false).include?(:compact!)
     # Replaces current hash with non +nil+ values.
-    # Returns nil if no changes were made, otherwise returns the hash.
+    # Returns +nil+ if no changes were made, otherwise returns the hash.
     #
     #   hash = { a: true, b: false, c: nil }
     #   hash.compact!        # => { a: true, b: false }
diff --git a/activesupport/lib/active_support/core_ext/kernel/reporting.rb b/activesupport/lib/active_support/core_ext/kernel/reporting.rb
index d0197af95f..c02618d5f3 100644
--- a/activesupport/lib/active_support/core_ext/kernel/reporting.rb
+++ b/activesupport/lib/active_support/core_ext/kernel/reporting.rb
@@ -1,7 +1,7 @@
 module Kernel
   module_function
 
-  # Sets $VERBOSE to nil for the duration of the block and back to its original
+  # Sets $VERBOSE to +nil+ for the duration of the block and back to its original
   # value afterwards.
   #
   #   silence_warnings do
diff --git a/activesupport/lib/active_support/core_ext/securerandom.rb b/activesupport/lib/active_support/core_ext/securerandom.rb
index b2e4fff79a..a57685bea1 100644
--- a/activesupport/lib/active_support/core_ext/securerandom.rb
+++ b/activesupport/lib/active_support/core_ext/securerandom.rb
@@ -6,7 +6,7 @@ module SecureRandom
   #
   # The argument _n_ specifies the length, of the random string to be generated.
   #
-  # If _n_ is not specified or is nil, 16 is assumed. It may be larger in the future.
+  # If _n_ is not specified or is +nil+, 16 is assumed. It may be larger in the future.
   #
   # The result may contain alphanumeric characters except 0, O, I and l
   #
diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb
index caa48e34c5..6133826f37 100644
--- a/activesupport/lib/active_support/core_ext/string/access.rb
+++ b/activesupport/lib/active_support/core_ext/string/access.rb
@@ -3,7 +3,7 @@ class String
   # position. The first character of the string is at position 0, the next at
   # position 1, and so on. If a range is supplied, a substring containing
   # characters at offsets given by the range is returned. In both cases, if an
-  # offset is negative, it is counted from the end of the string. Returns nil
+  # offset is negative, it is counted from the end of the string. Returns +nil+
   # if the initial offset falls outside the string. Returns an empty string if
   # the beginning of the range is greater than the end of the string.
   #
@@ -17,7 +17,7 @@ class String
   #
   # If a Regexp is given, the matching portion of the string is returned.
   # If a String is given, that given string is returned if it occurs in
-  # the string. In both cases, nil is returned if there is no match.
+  # the string. In both cases, +nil+ is returned if there is no match.
   #
   #   str = "hello"
   #   str.at(/lo/) # => "lo"
diff --git a/activesupport/lib/active_support/core_ext/string/inflections.rb b/activesupport/lib/active_support/core_ext/string/inflections.rb
index 7e12700c8c..765c0919bb 100644
--- a/activesupport/lib/active_support/core_ext/string/inflections.rb
+++ b/activesupport/lib/active_support/core_ext/string/inflections.rb
@@ -67,7 +67,7 @@ class String
   end
 
   # +safe_constantize+ tries to find a declared constant with the name specified
-  # in the string. It returns nil when the name is not in CamelCase
+  # in the string. It returns +nil+ when the name is not in CamelCase
   # or is not initialized.  See ActiveSupport::Inflector.safe_constantize
   #
   #   'Module'.safe_constantize  # => Module
diff --git a/activesupport/lib/active_support/json/encoding.rb b/activesupport/lib/active_support/json/encoding.rb
index cee731417f..8ff3551edc 100644
--- a/activesupport/lib/active_support/json/encoding.rb
+++ b/activesupport/lib/active_support/json/encoding.rb
@@ -68,7 +68,8 @@ module ActiveSupport
             :ESCAPE_REGEX_WITHOUT_HTML_ENTITIES, :EscapedString
 
           # Convert an object into a "JSON-ready" representation composed of
-          # primitives like Hash, Array, String, Numeric, and true/false/nil.
+          # primitives like Hash, Array, String, Numeric,
+          # and +true+/+false+/+nil+.
           # Recursively calls #as_json to the object to recursively build a
           # fully JSON-ready object.
           #
diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb
index 938e4ebb72..262f25b874 100644
--- a/activesupport/lib/active_support/multibyte/chars.rb
+++ b/activesupport/lib/active_support/multibyte/chars.rb
@@ -87,7 +87,7 @@ module ActiveSupport #:nodoc:
       end
 
       # Works like <tt>String#slice!</tt>, but returns an instance of
-      # Chars, or nil if the string was not modified. The string will not be
+      # Chars, or +nil+ if the string was not modified. The string will not be
       # modified if the range given is out of bounds
       #
       #   string = 'Welcome'
diff --git a/activesupport/lib/active_support/number_helper.rb b/activesupport/lib/active_support/number_helper.rb
index 7a49bbb960..6000ea44be 100644
--- a/activesupport/lib/active_support/number_helper.rb
+++ b/activesupport/lib/active_support/number_helper.rb
@@ -109,7 +109,7 @@ module ActiveSupport
     # * <tt>:locale</tt> - Sets the locale to be used for formatting
     #   (defaults to current locale).
     # * <tt>:precision</tt> - Sets the precision of the number
-    #   (defaults to 3). Keeps the number's precision if nil.
+    #   (defaults to 3). Keeps the number's precision if +nil+.
     # * <tt>:significant</tt> - If +true+, precision will be the number
     #   of significant_digits. If +false+, the number of fractional
     #   digits (defaults to +false+).
@@ -183,7 +183,7 @@ module ActiveSupport
     # * <tt>:locale</tt> - Sets the locale to be used for formatting
     #   (defaults to current locale).
     # * <tt>:precision</tt> - Sets the precision of the number
-    #   (defaults to 3). Keeps the number's precision if nil.
+    #   (defaults to 3). Keeps the number's precision if +nil+.
     # * <tt>:significant</tt> - If +true+, precision will be the number
     #   of significant_digits. If +false+, the number of fractional
     #   digits (defaults to +false+).
diff --git a/activesupport/lib/active_support/rescuable.rb b/activesupport/lib/active_support/rescuable.rb
index dc3f27a16d..135690cc42 100644
--- a/activesupport/lib/active_support/rescuable.rb
+++ b/activesupport/lib/active_support/rescuable.rb
@@ -74,7 +74,7 @@ module ActiveSupport
       #
       # If no handler matches the exception, check for a handler matching the
       # (optional) exception.cause. If no handler matches the exception or its
-      # cause, this returns nil so you can deal with unhandled exceptions.
+      # cause, this returns +nil+, so you can deal with unhandled exceptions.
       # Be sure to re-raise unhandled exceptions if this is what you expect.
       #
       #     begin
@@ -83,7 +83,7 @@ module ActiveSupport
       #       rescue_with_handler(exception) || raise
       #     end
       #
-      # Returns the exception if it was handled and nil if it was not.
+      # Returns the exception if it was handled and +nil+ if it was not.
       def rescue_with_handler(exception, object: self)
         if handler = handler_for_rescue(exception, object: object)
           handler.call exception
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index 887774961a..fd54bca4ff 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -166,7 +166,7 @@ def set_locale
   I18n.locale = extract_locale_from_tld || I18n.default_locale
 end
 
-# Get locale from top-level domain or return nil if such locale is not available
+# Get locale from top-level domain or return +nil+ if such locale is not available
 # You have to put something like:
 #   127.0.0.1 application.com
 #   127.0.0.1 application.it
diff --git a/railties/lib/rails.rb b/railties/lib/rails.rb
index 5d862e3fec..ee48043a50 100644
--- a/railties/lib/rails.rb
+++ b/railties/lib/rails.rb
@@ -53,7 +53,7 @@ module Rails
     end
 
     # Returns a Pathname object of the current Rails project,
-    # otherwise it returns nil if there is no project:
+    # otherwise it returns +nil+ if there is no project:
     #
     #   Rails.root
     #     # => #<Pathname:/Users/someuser/some/path/project>
@@ -100,7 +100,7 @@ module Rails
     end
 
     # Returns a Pathname object of the public folder of the current
-    # Rails project, otherwise it returns nil if there is no project:
+    # Rails project, otherwise it returns +nil+ if there is no project:
     #
     #   Rails.public_path
     #     # => #<Pathname:/Users/someuser/some/path/project/public>