Use h4 headings in AR::Associations method docs [ci-skip]

jonathanhefner · jonathanhefner · commit e2207c7bd492 · 2023-10-26T17:49:24.000-05:00
SDoc uses `h3` headings for method signatures, so to preserve heading hierarchy, method documentation should use `h4`, `h5`, or `h6`. (cherry picked from commit 3c38fe5)
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
@@ -1300,7 +1300,7 @@ module ClassMethods
         #   Returns a Relation of all of the associated objects, forcing a database read.
         #   An empty Relation is returned if none are found.
         #
-        # === Example
+        # ==== Example
         #
         # A <tt>Firm</tt> class declares <tt>has_many :clients</tt>, which will add:
         # * <tt>Firm#clients</tt> (similar to <tt>Client.where(firm_id: id)</tt>)
@@ -1321,7 +1321,7 @@ module ClassMethods
         # * <tt>Firm#clients.reload</tt>
         # The declaration can also include an +options+ hash to specialize the behavior of the association.
         #
-        # === Scopes
+        # ==== Scopes
         #
         # You can pass a second argument +scope+ as a callable (i.e. proc or
         # lambda) to retrieve a specific set of records or customize the generated
@@ -1332,7 +1332,7 @@ module ClassMethods
         #   has_many :employees, -> { joins(:address) }
         #   has_many :posts, ->(blog) { where("max_post_length > ?", blog.max_post_length) }
         #
-        # === Extensions
+        # ==== Extensions
         #
         # The +extension+ argument allows you to pass a block into a has_many
         # association. This is useful for adding new finders, creators, and other
@@ -1346,7 +1346,7 @@ module ClassMethods
         #     end
         #   end
         #
-        # === Options
+        # ==== Options
         # [+:class_name+]
         #   Specify the class name of the association. Use it only if that name can't be inferred
         #   from the association name. So <tt>has_many :products</tt> will by default be linked
@@ -1501,7 +1501,7 @@ def has_many(name, scope = nil, **options, &extension)
         # [<tt>reload_association</tt>]
         #   Returns the associated object, forcing a database read.
         #
-        # === Example
+        # ==== Example
         #
         # An Account class declares <tt>has_one :beneficiary</tt>, which will add:
         # * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.where(account_id: id).first</tt>)
@@ -1511,7 +1511,7 @@ def has_many(name, scope = nil, **options, &extension)
         # * <tt>Account#create_beneficiary!</tt> (similar to <tt>b = Beneficiary.new(account_id: id); b.save!; b</tt>)
         # * <tt>Account#reload_beneficiary</tt>
         #
-        # === Scopes
+        # ==== Scopes
         #
         # You can pass a second argument +scope+ as a callable (i.e. proc or
         # lambda) to retrieve a specific record or customize the generated query
@@ -1522,7 +1522,7 @@ def has_many(name, scope = nil, **options, &extension)
         #   has_one :employer, -> { joins(:company) }
         #   has_one :latest_post, ->(blog) { where("created_at > ?", blog.enabled_at) }
         #
-        # === Options
+        # ==== Options
         #
         # The declaration can also include an +options+ hash to specialize the behavior of the association.
         #
@@ -1674,7 +1674,7 @@ def has_one(name, scope = nil, **options)
         # [<tt>association_previously_changed?</tt>]
         #   Returns true if the previous save updated the association to reference a new associate object.
         #
-        # === Example
+        # ==== Example
         #
         # A Post class declares <tt>belongs_to :author</tt>, which will add:
         # * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)
@@ -1687,7 +1687,7 @@ def has_one(name, scope = nil, **options)
         # * <tt>Post#author_previously_changed?</tt>
         # The declaration can also include an +options+ hash to specialize the behavior of the association.
         #
-        # === Scopes
+        # ==== Scopes
         #
         # You can pass a second argument +scope+ as a callable (i.e. proc or
         # lambda) to retrieve a specific record or customize the generated query
@@ -1698,7 +1698,7 @@ def has_one(name, scope = nil, **options)
         #   belongs_to :user, -> { joins(:friends) }
         #   belongs_to :level, ->(game) { where("game_level > ?", game.current_level) }
         #
-        # === Options
+        # ==== Options
         #
         # [+:class_name+]
         #   Specify the class name of the association. Use it only if that name can't be inferred
@@ -1877,7 +1877,7 @@ def belongs_to(name, scope = nil, **options)
         #   Returns a Relation of all of the associated objects, forcing a database read.
         #   An empty Relation is returned if none are found.
         #
-        # === Example
+        # ==== Example
         #
         # A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:
         # * <tt>Developer#projects</tt>
@@ -1897,7 +1897,7 @@ def belongs_to(name, scope = nil, **options)
         # * <tt>Developer#projects.reload</tt>
         # The declaration may include an +options+ hash to specialize the behavior of the association.
         #
-        # === Scopes
+        # ==== Scopes
         #
         # You can pass a second argument +scope+ as a callable (i.e. proc or
         # lambda) to retrieve a specific set of records or customize the generated
@@ -1909,7 +1909,7 @@ def belongs_to(name, scope = nil, **options)
         #     where("default_category = ?", post.default_category)
         #   }
         #
-        # === Extensions
+        # ==== Extensions
         #
         # The +extension+ argument allows you to pass a block into a
         # has_and_belongs_to_many association. This is useful for adding new
@@ -1924,7 +1924,7 @@ def belongs_to(name, scope = nil, **options)
         #     end
         #   end
         #
-        # === Options
+        # ==== Options
         #
         # [+:class_name+]
         #   Specify the class name of the association. Use it only if that name can't be inferred

Original file line number	Diff line number	Diff line change
`@@ -1300,7 +1300,7 @@ module ClassMethods`
`1300`	`1300`	`# Returns a Relation of all of the associated objects, forcing a database read.`
`1301`	`1301`	`# An empty Relation is returned if none are found.`
`1302`	`1302`	`#`
`1303`		`- # === Example`
	`1303`	`+ # ==== Example`
`1304`	`1304`	`#`
`1305`	`1305`	`# A <tt>Firm</tt> class declares <tt>has_many :clients</tt>, which will add:`
`1306`	`1306`	`# * <tt>Firm#clients</tt> (similar to <tt>Client.where(firm_id: id)</tt>)`
`@@ -1321,7 +1321,7 @@ module ClassMethods`
`1321`	`1321`	`# * <tt>Firm#clients.reload</tt>`
`1322`	`1322`	`# The declaration can also include an +options+ hash to specialize the behavior of the association.`
`1323`	`1323`	`#`
`1324`		`- # === Scopes`
	`1324`	`+ # ==== Scopes`
`1325`	`1325`	`#`
`1326`	`1326`	`# You can pass a second argument +scope+ as a callable (i.e. proc or`
`1327`	`1327`	`# lambda) to retrieve a specific set of records or customize the generated`
`@@ -1332,7 +1332,7 @@ module ClassMethods`
`1332`	`1332`	`# has_many :employees, -> { joins(:address) }`
`1333`	`1333`	`# has_many :posts, ->(blog) { where("max_post_length > ?", blog.max_post_length) }`
`1334`	`1334`	`#`
`1335`		`- # === Extensions`
	`1335`	`+ # ==== Extensions`
`1336`	`1336`	`#`
`1337`	`1337`	`# The +extension+ argument allows you to pass a block into a has_many`
`1338`	`1338`	`# association. This is useful for adding new finders, creators, and other`
`@@ -1346,7 +1346,7 @@ module ClassMethods`
`1346`	`1346`	`# end`
`1347`	`1347`	`# end`
`1348`	`1348`	`#`
`1349`		`- # === Options`
	`1349`	`+ # ==== Options`
`1350`	`1350`	`# [+:class_name+]`
`1351`	`1351`	`# Specify the class name of the association. Use it only if that name can't be inferred`
`1352`	`1352`	`# from the association name. So <tt>has_many :products</tt> will by default be linked`
`@@ -1501,7 +1501,7 @@ def has_many(name, scope = nil, **options, &extension)`
`1501`	`1501`	`# [<tt>reload_association</tt>]`
`1502`	`1502`	`# Returns the associated object, forcing a database read.`
`1503`	`1503`	`#`
`1504`		`- # === Example`
	`1504`	`+ # ==== Example`
`1505`	`1505`	`#`
`1506`	`1506`	`# An Account class declares <tt>has_one :beneficiary</tt>, which will add:`
`1507`	`1507`	`# * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.where(account_id: id).first</tt>)`
`@@ -1511,7 +1511,7 @@ def has_many(name, scope = nil, **options, &extension)`
`1511`	`1511`	`# * <tt>Account#create_beneficiary!</tt> (similar to <tt>b = Beneficiary.new(account_id: id); b.save!; b</tt>)`
`1512`	`1512`	`# * <tt>Account#reload_beneficiary</tt>`
`1513`	`1513`	`#`
`1514`		`- # === Scopes`
	`1514`	`+ # ==== Scopes`
`1515`	`1515`	`#`
`1516`	`1516`	`# You can pass a second argument +scope+ as a callable (i.e. proc or`
`1517`	`1517`	`# lambda) to retrieve a specific record or customize the generated query`
`@@ -1522,7 +1522,7 @@ def has_many(name, scope = nil, **options, &extension)`
`1522`	`1522`	`# has_one :employer, -> { joins(:company) }`
`1523`	`1523`	`# has_one :latest_post, ->(blog) { where("created_at > ?", blog.enabled_at) }`
`1524`	`1524`	`#`
`1525`		`- # === Options`
	`1525`	`+ # ==== Options`
`1526`	`1526`	`#`
`1527`	`1527`	`# The declaration can also include an +options+ hash to specialize the behavior of the association.`
`1528`	`1528`	`#`
`@@ -1674,7 +1674,7 @@ def has_one(name, scope = nil, **options)`
`1674`	`1674`	`# [<tt>association_previously_changed?</tt>]`
`1675`	`1675`	`# Returns true if the previous save updated the association to reference a new associate object.`
`1676`	`1676`	`#`
`1677`		`- # === Example`
	`1677`	`+ # ==== Example`
`1678`	`1678`	`#`
`1679`	`1679`	`# A Post class declares <tt>belongs_to :author</tt>, which will add:`
`1680`	`1680`	`# * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)`
`@@ -1687,7 +1687,7 @@ def has_one(name, scope = nil, **options)`
`1687`	`1687`	`# * <tt>Post#author_previously_changed?</tt>`
`1688`	`1688`	`# The declaration can also include an +options+ hash to specialize the behavior of the association.`
`1689`	`1689`	`#`
`1690`		`- # === Scopes`
	`1690`	`+ # ==== Scopes`
`1691`	`1691`	`#`
`1692`	`1692`	`# You can pass a second argument +scope+ as a callable (i.e. proc or`
`1693`	`1693`	`# lambda) to retrieve a specific record or customize the generated query`
`@@ -1698,7 +1698,7 @@ def has_one(name, scope = nil, **options)`
`1698`	`1698`	`# belongs_to :user, -> { joins(:friends) }`
`1699`	`1699`	`# belongs_to :level, ->(game) { where("game_level > ?", game.current_level) }`
`1700`	`1700`	`#`
`1701`		`- # === Options`
	`1701`	`+ # ==== Options`
`1702`	`1702`	`#`
`1703`	`1703`	`# [+:class_name+]`
`1704`	`1704`	`# Specify the class name of the association. Use it only if that name can't be inferred`
`@@ -1877,7 +1877,7 @@ def belongs_to(name, scope = nil, **options)`
`1877`	`1877`	`# Returns a Relation of all of the associated objects, forcing a database read.`
`1878`	`1878`	`# An empty Relation is returned if none are found.`
`1879`	`1879`	`#`
`1880`		`- # === Example`
	`1880`	`+ # ==== Example`
`1881`	`1881`	`#`
`1882`	`1882`	`# A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:`
`1883`	`1883`	`# * <tt>Developer#projects</tt>`
`@@ -1897,7 +1897,7 @@ def belongs_to(name, scope = nil, **options)`
`1897`	`1897`	`# * <tt>Developer#projects.reload</tt>`
`1898`	`1898`	`# The declaration may include an +options+ hash to specialize the behavior of the association.`
`1899`	`1899`	`#`
`1900`		`- # === Scopes`
	`1900`	`+ # ==== Scopes`
`1901`	`1901`	`#`
`1902`	`1902`	`# You can pass a second argument +scope+ as a callable (i.e. proc or`
`1903`	`1903`	`# lambda) to retrieve a specific set of records or customize the generated`
`@@ -1909,7 +1909,7 @@ def belongs_to(name, scope = nil, **options)`
`1909`	`1909`	`# where("default_category = ?", post.default_category)`
`1910`	`1910`	`# }`
`1911`	`1911`	`#`
`1912`		`- # === Extensions`
	`1912`	`+ # ==== Extensions`
`1913`	`1913`	`#`
`1914`	`1914`	`# The +extension+ argument allows you to pass a block into a`
`1915`	`1915`	`# has_and_belongs_to_many association. This is useful for adding new`
`@@ -1924,7 +1924,7 @@ def belongs_to(name, scope = nil, **options)`
`1924`	`1924`	`# end`
`1925`	`1925`	`# end`
`1926`	`1926`	`#`
`1927`		`- # === Options`
	`1927`	`+ # ==== Options`
`1928`	`1928`	`#`
`1929`	`1929`	`# [+:class_name+]`
`1930`	`1930`	`# Specify the class name of the association. Use it only if that name can't be inferred`