Wrap method signatures in <code>

This factors out a `method_signature` helper that wraps method
signatures in `<code>` tags and ensures that signatures are always
HTML-escaped, including signatures from `:call-seq:` documentation.
Incidentally, this fixes a visual disparity between `:call-seq:`
signatures and normal method signatures due to the way they were wrapped
with `<b>` tags.

This commit also forces the postprocessor to use Nokogiri's `HTML5`
parser to prevent extraneous newlines from being inserted into a
signature's preformatted `<h3>` tag.

Author: jonathanhefner

lib/rdoc/generator/template/rails/_context.rhtml

@@ -130,14 +130,8 @@
     %>
       <h2 class="content__divider"><%= visibility.to_s.capitalize %> <%= type %> methods</h2>
       <% methods.each do |method| %>
-        <div class="method">
-          <h3 class="method__signature" id="<%= method.aref %>">
-            <% if method.call_seq %>
-              <b><%= method.call_seq.gsub(/->/, '&rarr;').gsub(/\n(.)/, '<br />\1') %></b>
-            <% else %>
-              <b><%= h method.name %></b><%= h method.params %>
-            <% end %>
-          </h3>
+        <div class="method" id="<%= method.aref %>">
+          <h3 class="method__signature"><%= method_signature method %></h3>
           <%= link_to "Link", method, class: "permalink", name: method.aref %>
 
           <% unless method.aliases.empty? %>

lib/rdoc/generator/template/rails/resources/css/main.css

@@ -486,6 +486,7 @@ html {
 .method__signature {
   font-size: 1.1em;
   font-weight: normal;
+  white-space: pre-wrap;
   padding-bottom: var(--space-sm);
   border-bottom: 2px solid var(--code-bg);
 }

lib/sdoc/helpers.rb

@@ -116,6 +116,17 @@ def more_less_ul(items, limit)
     end
   end
 
+  def method_signature(rdoc_method)
+    if rdoc_method.call_seq
+      rdoc_method.call_seq.split(/\n+/).map do |line|
+        # Support specifying a call-seq like `to_s -> string`
+        line.split(" -> ").map { |side| "<code>#{h side}</code>" }.join(" &rarr; ")
+      end.join("\n")
+    else
+      "<code>#{h rdoc_method.name}#{h rdoc_method.params}</code>"
+    end
+  end
+
   def method_source_code_and_url(rdoc_method)
     source_code = rdoc_method.markup_code if rdoc_method.token_stream
 

lib/sdoc/postprocessor.rb

@@ -7,7 +7,7 @@ module SDoc::Postprocessor
   extend self
 
   def process(rendered)
-    document = Nokogiri::HTML.parse(rendered)
+    document = Nokogiri::HTML5.parse(rendered)
 
     rebase_urls!(document)
     version_rails_guides_urls!(document)

spec/helpers_spec.rb

@@ -502,6 +502,50 @@ def ul(items)
     end
   end
 
+  describe "#method_signature" do
+    it "returns the method signature wrapped in <code>" do
+      method = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_method("bar", false)
+        module Foo; def bar(qux); end; end
+      RUBY
+
+      _(@helpers.method_signature(method)).must_equal "<code>bar(qux)</code>"
+    end
+
+    it "escapes the method signature" do
+      method = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_method("bar", false)
+        module Foo; def bar(op = :<, &block); end; end
+      RUBY
+
+      _(@helpers.method_signature(method)).must_equal "<code>bar(op = :&lt;, &amp;block)</code>"
+    end
+
+    it "handles :call-seq: documentation" do
+      mod = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
+        module Foo
+          # :call-seq:
+          #   bar(op = :<)
+          #   bar(&block)
+          def bar(*args, &block); end
+
+          # :call-seq:
+          #   qux(&block) -> self
+          #   qux -> Enumerator
+          def qux(&block); end
+        end
+      RUBY
+
+      _(@helpers.method_signature(mod.find_method("bar", false))).must_equal <<~HTML.chomp
+        <code>bar(op = :&lt;)</code>
+        <code>bar(&amp;block)</code>
+      HTML
+
+      _(@helpers.method_signature(mod.find_method("qux", false))).must_equal <<~HTML.chomp
+        <code>qux(&amp;block)</code> &rarr; <code>self</code>
+        <code>qux</code> &rarr; <code>Enumerator</code>
+      HTML
+    end
+  end
+
   describe "#method_source_code_and_url" do
     before :each do
       @helpers.options.github = true