diff --git a/.rdoc_options b/.rdoc_options
index 2826c2d5e8..910bdbaba5 100644
--- a/.rdoc_options
+++ b/.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
diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb
index 9b5de62fd6..172518c7f9 100644
--- a/lib/rdoc/markup/to_html_crossref.rb
+++ b/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,7 +92,7 @@ def handle_regexp_CROSSREF(target)
return name if name =~ /\A[a-z]*\z/
end
- cross_reference name
+ cross_reference name, rdoc_ref: false
end
##
@@ -100,9 +100,14 @@ def handle_regexp_CROSSREF(target)
# 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) : +""
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index a607a76d56..f35467e312 100644
--- a/lib/rdoc/options.rb
+++ b/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|
diff --git a/test/rdoc/test_rdoc_markup_to_html_crossref.rb b/test/rdoc/test_rdoc_markup_to_html_crossref.rb
index dc4488195a..d5817560e2 100644
--- a/test/rdoc/test_rdoc_markup_to_html_crossref.rb
+++ b/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("C1"), 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 "C2::C3", REGEXP_HANDLING('C2::C3')
end
diff --git a/test/rdoc/test_rdoc_options.rb b/test/rdoc/test_rdoc_options.rb
index 1fc56b2d5e..eb8477483c 100644
--- a/test/rdoc/test_rdoc_options.rb
+++ b/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