From f0bb0552ba2d5c085f89cb16e1b4e78d58587c97 Mon Sep 17 00:00:00 2001
From: st0012 <stan001212@gmail.com>
Date: Sat, 14 Mar 2026 23:02:32 +0000
Subject: [PATCH] Don't auto-link to non-text source files in cross-references

RDoc's cross-reference system auto-links filenames like `array.c`
when encountered in documentation text. However, non-text source
files are not meant to have their own documentation pages, so these
auto-generated links are always broken.

Only suppress auto-linking. Explicit `rdoc-ref:` links to non-text
files (enabled by #1376) continue to work.
---
 lib/rdoc/markup/to_html_crossref.rb       |  6 ++++++
 test/rdoc/markup/to_html_crossref_test.rb | 19 +++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb
index e088303801..106810072b 100644
--- a/lib/rdoc/markup/to_html_crossref.rb
+++ b/lib/rdoc/markup/to_html_crossref.rb
@@ -159,6 +159,12 @@ def link(name, text, code = true, rdoc_ref: false)
 
     ref = @cross_reference.resolve name, text if name
 
+    # Non-text source files (C, Ruby, etc.) don't get HTML pages generated,
+    # so don't auto-link to them. Explicit rdoc-ref: links are still allowed.
+    if !rdoc_ref && RDoc::TopLevel === ref && !ref.text?
+      return text
+    end
+
     case ref
     when String then
       if rdoc_ref && @warn_missing_rdoc_ref
diff --git a/test/rdoc/markup/to_html_crossref_test.rb b/test/rdoc/markup/to_html_crossref_test.rb
index 802acb7063..ff243fc9e0 100644
--- a/test/rdoc/markup/to_html_crossref_test.rb
+++ b/test/rdoc/markup/to_html_crossref_test.rb
@@ -387,6 +387,25 @@ def test_to_html_CROSSREF_email_hyperlink_all
     assert_equal 'first.last@example.com', result
   end
 
+  def test_convert_CROSSREF_c_file_not_autolinked
+    # C files are not text files, so they don't get HTML pages generated.
+    # Auto cross-references to them should not produce links.
+    c_file = @store.add_file 'array.c'
+    c_file.parser = RDoc::Parser::C
+
+    result = @to.convert 'array.c'
+    assert_equal para("array.c"), result
+  end
+
+  def test_convert_RDOCLINK_rdoc_ref_c_file_linked
+    # Explicit rdoc-ref: links to non-text files should still work.
+    c_file = @store.add_file 'array.c'
+    c_file.parser = RDoc::Parser::C
+
+    result = @to.convert 'rdoc-ref:array.c'
+    assert_equal para("<a href=\"array_c.html\">array.c</a>"), result
+  end
+
   def test_link
     assert_equal 'n', @to.link('n', 'n')