Print warnings for rdoc-ref links that can't be resolved

.rdoc_options

@@ -6,3 +6,4 @@ exclude:
 op_dir: _site # for GitHub Pages and should match the config of RDoc task in Rakefile
 title: rdoc Documentation
 main_page: README.rdoc
+warn_missing_rdoc_ref: true

lib/rdoc/markup/to_html_crossref.rb

@@ -58,7 +58,7 @@ def init_link_notation_regexp_handlings
   # Creates a link to the reference +name+ if the name exists.  If +text+ is
   # given it is used as the link text, otherwise +name+ is used.
 
-  def cross_reference name, text = nil, code = true
+  def cross_reference name, text = nil, code = true, rdoc_ref: false
     lookup = name
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
@@ -70,7 +70,7 @@ def cross_reference name, text = nil, code = true
       text ||= name
     end
 
-    link lookup, text, code
+    link lookup, text, code, rdoc_ref: rdoc_ref
   end
 
   ##
@@ -92,17 +92,22 @@ def handle_regexp_CROSSREF(target)
       return name if name =~ /\A[a-z]*\z/
     end
 
-    cross_reference name
+    cross_reference name, rdoc_ref: false
   end
 
   ##
   # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
   # handle other schemes.
 
   def handle_regexp_HYPERLINK target
-    return cross_reference $' if target.text =~ /\Ardoc-ref:/
+    url = target.text
 
-    super
+    case url
+    when /\Ardoc-ref:/
+      cross_reference $', rdoc_ref: true
+    else
+      super
+    end
   end
 
   ##
@@ -117,8 +122,8 @@ def handle_regexp_RDOCLINK target
     url = target.text
 
     case url
-    when /\Ardoc-ref:/ then
-      cross_reference $'
+    when /\Ardoc-ref:/
+      cross_reference $', rdoc_ref: true
     else
       super
     end
@@ -129,16 +134,18 @@ def handle_regexp_RDOCLINK target
   # RDoc::Markup::ToHtml to handle other schemes.
 
   def gen_url url, text
-    return super unless url =~ /\Ardoc-ref:/
-
-    name = $'
-    cross_reference name, text, name == text
+    if url =~ /\Ardoc-ref:/
+      name = $'
+      cross_reference name, text, name == text, rdoc_ref: true
+    else
+      super
+    end
   end
 
   ##
   # Creates an HTML link to +name+ with the given +text+.
 
-  def link name, text, code = true
+  def link name, text, code = true, rdoc_ref: false
     if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
       name = $1
       label = $'
@@ -148,6 +155,9 @@ def link name, text, code = true
 
     case ref
     when String then
+      if rdoc_ref && @options.warn_missing_rdoc_ref
+        puts "#{@from_path}: `rdoc-ref:#{name}` can't be resolved for `#{text}`"
+      end
       ref
     else
       path = ref ? ref.as_href(@from_path) : +""

lib/rdoc/options.rb

@@ -325,6 +325,12 @@ class RDoc::Options
 
   attr_accessor :verbosity
 
+  ##
+  # Warn if rdoc-ref links can't be resolved
+  # Default is +false+
+
+  attr_accessor :warn_missing_rdoc_ref
+
   ##
   # URL of web cvs frontend
 
@@ -393,6 +399,7 @@ def init_ivars # :nodoc:
     @update_output_dir = true
     @verbosity = 1
     @visibility = :protected
+    @warn_missing_rdoc_ref = false
     @webcvs = nil
     @write_options = false
     @encoding = Encoding::UTF_8
@@ -457,6 +464,8 @@ def override map # :nodoc:
     @visibility     = map['visibility']     if map.has_key?('visibility')
     @webcvs         = map['webcvs']         if map.has_key?('webcvs')
 
+    @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
+
     if map.has_key?('rdoc_include')
       @rdoc_include = sanitize_path map['rdoc_include']
     end
@@ -1104,6 +1113,13 @@ def parse argv
 
       opt.separator nil
 
+      opt.on("--warn-missing-rdoc-ref",
+             "Warn if rdoc-ref links can't be resolved") do |value|
+        @warn_missing_rdoc_ref = value
+      end
+
+      opt.separator nil
+
       opt.on("--[no-]ignore-invalid",
              "Ignore invalid options and continue",
              "(default true).") do |value|

test/rdoc/test_rdoc_markup_to_html_crossref.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 require_relative 'xref_test_case'
 
-class TestRDocMarkupToHtmlCrossref < XrefTestCase
+class RDocMarkupToHtmlCrossrefTest < XrefTestCase
 
   def setup
     super
 
     @options.hyperlink_all = true
+    @options.warn_missing_rdoc_ref = true
 
     @to = RDoc::Markup::ToHtmlCrossref.new @options, 'index.html', @c1
   end
@@ -67,6 +68,16 @@ def test_convert_RDOCLINK_rdoc_ref
     assert_equal para("<a href=\"C1.html\"><code>C1</code></a>"), result
   end
 
+  def test_convert_RDOCLINK_rdoc_ref_not_found
+    result = nil
+    stdout, _ = capture_output do
+      result = @to.convert 'rdoc-ref:FOO'
+    end
+
+    assert_equal para("FOO"), result
+    assert_include stdout, "index.html: `rdoc-ref:FOO` can't be resolved for `FOO`"
+  end
+
   def test_convert_RDOCLINK_rdoc_ref_method
     result = @to.convert 'rdoc-ref:C1#m'
 
@@ -153,6 +164,14 @@ def test_gen_url
                  @to.gen_url('http://example', 'HTTP example')
   end
 
+  def test_gen_url_rdoc_ref_not_found
+    stdout, _ = capture_output do
+      @to.gen_url 'rdoc-ref:FOO', 'FOO'
+    end
+
+    assert_include stdout, "index.html: `rdoc-ref:FOO` can't be resolved for `FOO`"
+  end
+
   def test_handle_regexp_CROSSREF
     assert_equal "<a href=\"C2/C3.html\"><code>C2::C3</code></a>", REGEXP_HANDLING('C2::C3')
   end

test/rdoc/test_rdoc_options.rb

@@ -63,27 +63,28 @@ def test_to_yaml
     encoding = 'UTF-8'
 
     expected = {
-      'charset'              => 'UTF-8',
-      'encoding'             => encoding,
-      'embed_mixins'         => false,
-      'exclude'              => %w[~\z \.orig\z \.rej\z \.bak\z \.gemspec\z],
-      'hyperlink_all'        => false,
-      'line_numbers'         => false,
-      'locale_dir'           => 'locale',
-      'locale_name'          => nil,
-      'main_page'            => nil,
-      'markup'               => 'rdoc',
-      'output_decoration'    => true,
-      'page_dir'             => nil,
-      'rdoc_include'         => [],
-      'show_hash'            => false,
-      'static_path'          => [],
-      'tab_width'            => 8,
-      'template_stylesheets' => [],
-      'title'                => nil,
-      'visibility'           => :protected,
-      'webcvs'               => nil,
-      'skip_tests'           => true,
+      'charset'               => 'UTF-8',
+      'encoding'              => encoding,
+      'embed_mixins'          => false,
+      'exclude'               => %w[~\z \.orig\z \.rej\z \.bak\z \.gemspec\z],
+      'hyperlink_all'         => false,
+      'line_numbers'          => false,
+      'locale_dir'            => 'locale',
+      'locale_name'           => nil,
+      'main_page'             => nil,
+      'markup'                => 'rdoc',
+      'output_decoration'     => true,
+      'page_dir'              => nil,
+      'rdoc_include'          => [],
+      'show_hash'             => false,
+      'static_path'           => [],
+      'tab_width'             => 8,
+      'template_stylesheets'  => [],
+      'title'                 => nil,
+      'visibility'            => :protected,
+      'warn_missing_rdoc_ref' => false,
+      'webcvs'                => nil,
+      'skip_tests'            => true,
     }
 
     assert_equal expected, coder