From 4837fea087618a3811f246d466a5af9346802369 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Thu, 27 Jul 2023 21:57:54 -0500
Subject: [PATCH] Unlink unintentional autolinked code ref links

RDoc can be overzealous when autolinking words that look like module
names.  For example, autolinking every occurrence of "Rails" or "ERB".

This commit uses postprocessing to unlink autolinked code ref links that
appear to be unintentional.  If a link's text is an uppercase letter
followed by either all lowercase letters (e.g. "Rails") or all uppercase
letters (e.g. "ERB"), then it's assumed the link is unintentional, and
the link is replaced with the just its text.

These kinds of modules can still be linked by prepending the module
namespace (e.g. "::ERB" or "ActionView::Template::Handlers::ERB"), or by
manually linking the text (e.g. "{Rails}[rdoc-ref:Rails]").
---
 lib/sdoc/postprocessor.rb  |  9 +++++++++
 spec/postprocessor_spec.rb | 30 ++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/lib/sdoc/postprocessor.rb b/lib/sdoc/postprocessor.rb
index 302ae6c3..65b3cb47 100644
--- a/lib/sdoc/postprocessor.rb
+++ b/lib/sdoc/postprocessor.rb
@@ -11,6 +11,7 @@ def process(rendered)
 
     rebase_urls!(document)
     version_rails_guides_urls!(document)
+    unlink_unintentional_ref_links!(document)
     highlight_code_blocks!(document)
 
     document.to_s
@@ -69,6 +70,14 @@ def version_url(url, version)
     uri.to_s
   end
 
+  def unlink_unintentional_ref_links!(document)
+    document.css(".description a[href^='classes/'] > code:only-child > text()").each do |text_node|
+      if text_node.inner_text.match?(/\A[A-Z](?:[A-Z]+|[a-z]+)\z/)
+        text_node.parent.parent.replace(text_node)
+      end
+    end
+  end
+
   def highlight_code_blocks!(document)
     document.css(".description pre > code, .sourcecode pre > code").each do |element|
       code = element.inner_text
diff --git a/spec/postprocessor_spec.rb b/spec/postprocessor_spec.rb
index 29c3f766..b6615538 100644
--- a/spec/postprocessor_spec.rb
+++ b/spec/postprocessor_spec.rb
@@ -61,6 +61,36 @@
       end
     end
 
+    it "unlinks unintentional autolinked code ref links in descriptions" do
+      rendered = <<~HTML
+        <base href="../" data-current-path="classes/Foo.html">
+
+        <div class="description">
+          <a href="Rails.html"><code>Rails</code></a>
+          <a href="ERB.html"><code>ERB</code></a>
+
+          <a href="Rails.html"><code>::Rails</code></a>
+          <a href="FooBar.html"><code>FooBar</code></a>
+        </div>
+
+        <a href="Nav.html"><code>Nav</code></a>
+      HTML
+
+      expected = <<~HTML
+        <div class="description">
+          Rails
+          ERB
+
+          <a href="classes/Rails.html"><code>::Rails</code></a>
+          <a href="classes/FooBar.html"><code>FooBar</code></a>
+        </div>
+
+        <a href="classes/Nav.html"><code>Nav</code></a>
+      HTML
+
+      _(SDoc::Postprocessor.process(rendered)).must_include expected
+    end
+
     it "highlights code blocks" do
       rendered = <<~HTML
         <div class="description">