Split up code blocks for multi-file examples [ci-skip]

RDoc treats consecutive indented lines as a single code block. For code examples that span multiple files / languages, this confuses the syntax highlighter and makes the examples harder to read. Unfortunately, RDoc doesn't provide syntax to prevent this, and it ignores multiple consecutive blank lines. However, by inserting an empty tag such as `<code></code>`, we can force RDoc to recognize separate code blocks. (cherry picked from commit d1411b2)
rails · Jan 7, 2024 · bacab83 · bacab83
1 parent d0c2847
commit bacab83
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 4 deletions.
diff --git a/actionview/lib/action_view/helpers/form_helper.rb b/actionview/lib/action_view/helpers/form_helper.rb
@@ -1114,6 +1114,8 @@ def fields(scope = nil, model: nil, **options, &block)
       #       post:
       #         cost: "Total cost"
       #
+      # <code></code>
+      #
       #   label(:post, :cost)
       #   # => <label for="post_cost">Total cost</label>
       #
@@ -2333,6 +2335,8 @@ def fields(scope = nil, model: nil, **options, &block)
       #       post:
       #         cost: "Total cost"
       #
+      # <code></code>
+      #
       #   label(:cost)
       #   # => <label for="post_cost">Total cost</label>
       #

diff --git a/actionview/lib/action_view/helpers/sanitize_helper.rb b/actionview/lib/action_view/helpers/sanitize_helper.rb
@@ -57,6 +57,8 @@ module SanitizeHelper
       #     end
       #   end
       #
+      # <code></code>
+      #
       #   <%= sanitize @comment.body, scrubber: CommentScrubber.new %>
       #
       # See {Rails HTML Sanitizer}[https://github.com/rails/rails-html-sanitizer] for
@@ -68,6 +70,8 @@ module SanitizeHelper
       #     node.remove if node.name == 'script'
       #   end
       #
+      # <code></code>
+      #
       #   <%= sanitize @comment.body, scrubber: scrubber %>
       #
       # See {Loofah's documentation}[https://github.com/flavorjones/loofah] for more

diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb
@@ -258,6 +258,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #     name: Reginald the Pirate
   #     monkey_id: 1
   #
+  # <code></code>
+  #
   #   ### in monkeys.yml
   #
   #   george:
@@ -275,6 +277,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #     name: Reginald the Pirate
   #     monkey: george
   #
+  # <code></code>
+  #
   #   ### in monkeys.yml
   #
   #   george:
@@ -296,6 +300,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #
   #   belongs_to :eater, polymorphic: true
   #
+  # <code></code>
+  #
   #   ### in fruits.yml
   #
   #   apple:
@@ -321,6 +327,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #     id: 1
   #     name: George the Monkey
   #
+  # <code></code>
+  #
   #   ### in fruits.yml
   #
   #   apple:
@@ -335,6 +343,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #     id: 3
   #     name: grape
   #
+  # <code></code>
+  #
   #   ### in fruits_monkeys.yml
   #
   #   apple_george:
@@ -358,6 +368,8 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError # :nodoc:
   #     name: George the Monkey
   #     fruits: apple, orange, grape
   #
+  # <code></code>
+  #
   #   ### in fruits.yml
   #
   #   apple:

diff --git a/activestorage/lib/active_storage/fixture_set.rb b/activestorage/lib/active_storage/fixture_set.rb
@@ -24,9 +24,13 @@ module ActiveStorage
   #     has_one_attached :thumbnail
   #   end
   #
+  # <code></code>
+  #
   #   # fixtures/active_storage/blobs.yml
   #   first_thumbnail_blob: <%= ActiveStorage::FixtureSet.blob filename: "first.png" %>
   #
+  # <code></code>
+  #
   #   # fixtures/active_storage/attachments.yml
   #   first_thumbnail_attachment:
   #     name: thumbnail

diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb
@@ -184,8 +184,7 @@ def message_verifier(verifier_name)
     end
 
     # Convenience for loading config/foo.yml for the current Rails env.
-    #
-    # Examples:
+    # Example:
     #
     #     # config/exception_notification.yml:
     #     production:
@@ -196,13 +195,15 @@ def message_verifier(verifier_name)
     #       url: http://localhost:3001
     #       namespace: my_app_development
     #
+    # <code></code>
+    #
     #     # config/environments/production.rb
     #     Rails.application.configure do
     #       config.middleware.use ExceptionNotifier, config_for(:exception_notification)
     #     end
     #
-    #     # You can also store configurations in a shared section which will be
-    #     # merged with the environment configuration
+    # You can also store configurations in a shared section which will be merged
+    # with the environment configuration
     #
     #     # config/example.yml
     #     shared:
@@ -215,6 +216,8 @@ def message_verifier(verifier_name)
     #         bar:
     #           qux: 2
     #
+    # <code></code>
+    #
     #     # development environment
     #     Rails.application.config_for(:example)[:foo][:bar]
     #     # => { baz: 1, qux: 2 }