vale.

Library/Homebrew/extend/hash/keys.rb

@@ -5,14 +5,18 @@ class Hash
   # Validates all keys in a hash match `*valid_keys`, raising
   # `ArgumentError` on a mismatch.
   #
-  # Note that keys are treated differently than HashWithIndifferentAccess,
+  # Note that keys are treated differently than `HashWithIndifferentAccess`,
   # meaning that string and symbol keys will not match.
   #
-  #     { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age)
-  #     # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age"
-  #     { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age')
-  #     # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'"
-  #     { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age)   # => passes, raises nothing
+  # ### Example#
+  #
+  # ```ruby
+  # { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age)
+  # # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age"
+  # { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age')
+  # # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'"
+  # { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age)   # => passes, raises nothing
+  # ```
   sig { params(valid_keys: T.untyped).void }
   def assert_valid_keys(*valid_keys)
     valid_keys.flatten!
@@ -28,10 +32,14 @@ def assert_valid_keys(*valid_keys)
   # This includes the keys from the root hash and from all
   # nested hashes and arrays.
   #
-  #     hash = { person: { name: 'Rob', age: '28' } }
+  # ### Example
+  #
+  # ```ruby
+  # hash = { person: { name: 'Rob', age: '28' } }
   #
-  #     hash.deep_transform_keys{ |key| key.to_s.upcase }
-  #     # => {"PERSON"=>{"NAME"=>"Rob", "AGE"=>"28"}}
+  # hash.deep_transform_keys{ |key| key.to_s.upcase }
+  # # => {"PERSON"=>{"NAME"=>"Rob", "AGE"=>"28"}}
+  # ```
   def deep_transform_keys(&block) = _deep_transform_keys_in_object(self, &block)
 
   # Destructively converts all keys by using the block operation.
@@ -43,10 +51,14 @@ def deep_transform_keys!(&block) = _deep_transform_keys_in_object!(self, &block)
   # This includes the keys from the root hash and from all
   # nested hashes and arrays.
   #
-  #     hash = { person: { name: 'Rob', age: '28' } }
+  # ### Example
   #
-  #     hash.deep_stringify_keys
-  #     # => {"person"=>{"name"=>"Rob", "age"=>"28"}}
+  # ```ruby
+  # hash = { person: { name: 'Rob', age: '28' } }
+  #
+  # hash.deep_stringify_keys
+  # # => {"person"=>{"name"=>"Rob", "age"=>"28"}}
+  # ```
   def deep_stringify_keys = T.unsafe(self).deep_transform_keys(&:to_s)
 
   # Destructively converts all keys to strings.
@@ -55,13 +67,17 @@ def deep_stringify_keys = T.unsafe(self).deep_transform_keys(&:to_s)
   def deep_stringify_keys! = T.unsafe(self).deep_transform_keys!(&:to_s)
 
   # Returns a new hash with all keys converted to symbols, as long as
-  # they respond to +to_sym+. This includes the keys from the root hash
+  # they respond to `to_sym`. This includes the keys from the root hash
   # and from all nested hashes and arrays.
   #
-  #     hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } }
+  # ### Example
+  #
+  # ```ruby
+  # hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } }
   #
-  #     hash.deep_symbolize_keys
-  #     # => {:person=>{:name=>"Rob", :age=>"28"}}
+  # hash.deep_symbolize_keys
+  # # => {:person=>{:name=>"Rob", :age=>"28"}}
+  # ```
   def deep_symbolize_keys
     deep_transform_keys do |key|
       T.unsafe(key).to_sym
@@ -71,7 +87,7 @@ def deep_symbolize_keys
   end
 
   # Destructively converts all keys to symbols, as long as they respond
-  # to +to_sym+. This includes the keys from the root hash and from all
+  # to `to_sym`. This includes the keys from the root hash and from all
   # nested hashes and arrays.
   def deep_symbolize_keys!
     deep_transform_keys! do |key|
@@ -102,7 +118,7 @@ def _deep_transform_keys_in_object(object, &block)
   def _deep_transform_keys_in_object!(object, &block)
     case object
     when Hash
-      # We can't use `each_key` here because we're updating the hash in-place
+      # We can't use `each_key` here because we're updating the hash in-place.
       object.keys.each do |key| # rubocop:disable Style/HashEachMethods
         value = object.delete(key)
         object[yield(key)] = _deep_transform_keys_in_object!(value, &block)