From 8aca2d48590cda8467b989c08b41cb2e18d65f3a Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Sat, 28 Dec 2024 17:18:14 +0000
Subject: [PATCH] Add autolink_excluded_words option to ignore cross-references

This config will be handy when the project name is the same as a class or
module name, which is often the case for most of the projects.
---
 lib/rdoc/markup/to_html_crossref.rb           |  2 ++
 lib/rdoc/options.rb                           | 20 +++++++++++++++++--
 .../rdoc/test_rdoc_markup_to_html_crossref.rb | 17 ++++++++++++++++
 test/rdoc/test_rdoc_options.rb                |  1 +
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb
index e6661b621e..06fee91a11 100644
--- a/lib/rdoc/markup/to_html_crossref.rb
+++ b/lib/rdoc/markup/to_html_crossref.rb
@@ -83,6 +83,8 @@ def cross_reference name, text = nil, code = true, rdoc_ref: false
   def handle_regexp_CROSSREF(target)
     name = target.text
 
+    return name if @options.autolink_excluded_words&.include?(name)
+
     return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails
 
     unless @hyperlink_all then
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index 5e2d320c73..d6c8db2c28 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -359,6 +359,10 @@ class RDoc::Options
   # Exclude the default patterns as well if true.
   attr_reader :apply_default_exclude
 
+  ##
+  # Words to be ignored in autolink cross-references
+  attr_accessor :autolink_excluded_words
+
   def initialize loaded_options = nil # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -370,6 +374,7 @@ def initialize loaded_options = nil # :nodoc:
   ]
 
   def init_ivars # :nodoc:
+    @autolink_excluded_words = []
     @dry_run = false
     @embed_mixins = false
     @exclude = []
@@ -437,7 +442,9 @@ def init_with map # :nodoc:
     @title          = map['title']
     @visibility     = map['visibility']
     @webcvs         = map['webcvs']
-    @apply_default_exclude = map['apply_default_exclude']
+
+    @apply_default_exclude   = map['apply_default_exclude']
+    @autolink_excluded_words = map['autolink_excluded_words']
 
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
@@ -471,6 +478,7 @@ def override map # :nodoc:
     @title          = map['title']          if map.has_key?('title')
     @visibility     = map['visibility']     if map.has_key?('visibility')
     @webcvs         = map['webcvs']         if map.has_key?('webcvs')
+    @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
     @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
 
     @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
@@ -503,7 +511,8 @@ def == other # :nodoc:
       @title          == other.title          and
       @visibility     == other.visibility     and
       @webcvs         == other.webcvs         and
-      @apply_default_exclude == other.apply_default_exclude
+      @apply_default_exclude == other.apply_default_exclude and
+      @autolink_excluded_words == other.autolink_excluded_words
   end
 
   ##
@@ -989,6 +998,13 @@ def parse argv
 
       opt.separator nil
 
+      opt.on("--autolink-excluded-words=WORDS", Array,
+             "Words to be ignored in autolink cross-references") do |value|
+        @autolink_excluded_words.concat value
+      end
+
+      opt.separator nil
+
       opt.on("--hyperlink-all", "-A",
              "Generate hyperlinks for all words that",
              "correspond to known methods, even if they",
diff --git a/test/rdoc/test_rdoc_markup_to_html_crossref.rb b/test/rdoc/test_rdoc_markup_to_html_crossref.rb
index fb0aca2909..5826f3d095 100644
--- a/test/rdoc/test_rdoc_markup_to_html_crossref.rb
+++ b/test/rdoc/test_rdoc_markup_to_html_crossref.rb
@@ -20,6 +20,9 @@ def test_convert_CROSSREF
     result = @to.convert '+C1+'
     assert_equal para("<a href=\"C1.html\"><code>C1</code></a>"), result
 
+    result = @to.convert 'Constant[rdoc-ref:C1]'
+    assert_equal para("<a href=\"C1.html\">Constant</a>"), result
+
     result = @to.convert 'FOO'
     assert_equal para("FOO"), result
 
@@ -30,6 +33,20 @@ def test_convert_CROSSREF
     assert_equal para("<code># :stopdoc:</code>:"), result
   end
 
+  def test_convert_CROSSREF_ignored_excluded_words
+    @options.autolink_excluded_words = ['C1']
+
+    result = @to.convert 'C1'
+    assert_equal para("C1"), result
+
+    result = @to.convert '+C1+'
+    assert_equal para("<a href=\"C1.html\"><code>C1</code></a>"), result
+
+    # Explicit linking with rdoc-ref is not ignored
+    result = @to.convert 'Constant[rdoc-ref:C1]'
+    assert_equal para("<a href=\"C1.html\">Constant</a>"), result
+  end
+
   def test_convert_CROSSREF_method
     result = @to.convert 'C1#m(foo, bar, baz)'
 
diff --git a/test/rdoc/test_rdoc_options.rb b/test/rdoc/test_rdoc_options.rb
index e658d4b314..9fc6830239 100644
--- a/test/rdoc/test_rdoc_options.rb
+++ b/test/rdoc/test_rdoc_options.rb
@@ -86,6 +86,7 @@ def test_to_yaml
       'webcvs'                => nil,
       'skip_tests'            => true,
       'apply_default_exclude' => true,
+      'autolink_excluded_words' => [],
     }
 
     assert_equal expected, coder