From 9a6460a0f1e835ff5b464fb8883ad404aec4fa3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Justin=20Malc=CC=8Cic=CC=81?= <j.malcic@me.com>
Date: Fri, 27 Dec 2024 14:56:27 +0000
Subject: [PATCH 1/4] Add helper for section comments

---
 lib/sdoc/helpers.rb  |  6 ++++++
 spec/helpers_spec.rb | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/lib/sdoc/helpers.rb b/lib/sdoc/helpers.rb
index d608f112..6fbc8942 100644
--- a/lib/sdoc/helpers.rb
+++ b/lib/sdoc/helpers.rb
@@ -64,6 +64,12 @@ def description_for(rdoc_object)
     end
   end
 
+  def comments_for(context, section)
+    return if section.comments.empty?
+
+    %(<div class="description">#{context.markup section.comments}</div>)
+  end
+
   def base_tag_for_context(context)
     relative_root = "../" * context.path.count("/")
     %(<base href="./#{relative_root}" data-current-path="#{context.path}">)
diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb
index 2d51b9ab..0a06edf7 100644
--- a/spec/helpers_spec.rb
+++ b/spec/helpers_spec.rb
@@ -300,6 +300,39 @@ module Foo; end
     end
   end
 
+  describe "#comments_for" do
+    it "returns RDoc::Context::Section#comments wrapped in div.description" do
+      rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
+        module Foo
+          # :section: Section 1
+          # First comment for Section 1 in Foo.
+
+          # :section: Section 1
+          # Second comment for Section 1 in Foo.
+        end
+      RUBY
+
+      _(@helpers.comments_for(rdoc_module, rdoc_module.sections.last)).
+        must_equal <<~HTML.chomp
+          <div class="description">
+          <p>First comment for Section 1 in <code>Foo</code>.</p>
+
+          <p>Second comment for Section 1 in <code>Foo</code>.</p>
+          </div>
+        HTML
+    end
+
+    it "returns nil when RDoc::CodeObject#description is empty" do
+      rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
+        module Foo
+          # :section: One
+        end
+      RUBY
+
+      _(@helpers.comments_for(rdoc_module, rdoc_module.sections.last)).must_be_nil
+    end
+  end
+
   describe "#base_tag_for_context" do
     it "returns a <base> tag with an appropriate path for the given RDoc::Context" do
       top_level = rdoc_top_level_for <<~RUBY

From 43e2184d0ca5c7b08b83c800564454e13087282e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Justin=20Malc=CC=8Cic=CC=81?= <j.malcic@me.com>
Date: Fri, 27 Dec 2024 14:56:57 +0000
Subject: [PATCH 2/4] Use new helper in template

---
 lib/rdoc/generator/template/rails/_context.rhtml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
index d4b1bfab..a3558d13 100644
--- a/lib/rdoc/generator/template/rails/_context.rhtml
+++ b/lib/rdoc/generator/template/rails/_context.rhtml
@@ -52,7 +52,7 @@
       </div>
     <% end %>
 
-    <%= description_for section %>
+    <%= comments_for @context, section %>
 
     <!-- Constants -->
     <% unless constants.empty? %>

From 9b4ed2c476042ccfae921aa76576ab817bccd863 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Justin=20Malc=CC=8Cic=CC=81?= <j.malcic@me.com>
Date: Fri, 27 Dec 2024 17:33:49 +0000
Subject: [PATCH 3/4] Fix unrelated failure

(cherry picked from commit 83493018439401c2f89ff7c78591a7fc2202ef0c)
---
 lib/sdoc/rdoc_monkey_patches.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/sdoc/rdoc_monkey_patches.rb b/lib/sdoc/rdoc_monkey_patches.rb
index ce858e5e..354ed62f 100644
--- a/lib/sdoc/rdoc_monkey_patches.rb
+++ b/lib/sdoc/rdoc_monkey_patches.rb
@@ -32,7 +32,7 @@ def params
 
 
 RDoc::Markup::ToHtmlCrossref.prepend(Module.new do
-  def cross_reference(name, text = nil, code = true)
+  def cross_reference(name, text = nil, code = true, rdoc_ref: false)
     if text
       # Style ref links that look like code, such as `{Rails}[rdoc-ref:Rails]`.
       code ||= !text.include?(" ") || text.match?(/\S\(/)

From ce53b073677326989304caa4e8dd2391fb0ea060 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Justin=20Malc=CC=8Cic=CC=81?= <j.malcic@me.com>
Date: Fri, 27 Dec 2024 17:38:21 +0000
Subject: [PATCH 4/4] Add missing markup in test

---
 spec/helpers_spec.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb
index 0a06edf7..12ac93e8 100644
--- a/spec/helpers_spec.rb
+++ b/spec/helpers_spec.rb
@@ -305,10 +305,10 @@ module Foo; end
       rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
         module Foo
           # :section: Section 1
-          # First comment for Section 1 in Foo.
+          # First comment for Section 1 in +Foo+.
 
           # :section: Section 1
-          # Second comment for Section 1 in Foo.
+          # Second comment for Section 1 in +Foo+.
         end
       RUBY