From 10ddb5115c0b9c1d8faae7f573cf046565d20e3b Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 13 Dec 2024 19:20:17 +0000 Subject: [PATCH] Print warnings for rdoc-ref links that can't be resolved --- .rdoc_options | 1 + lib/rdoc/markup/to_html_crossref.rb | 34 ++++++++++++------- lib/rdoc/options.rb | 16 +++++++++ .../rdoc/test_rdoc_markup_to_html_crossref.rb | 20 ++++++++++- 4 files changed, 58 insertions(+), 13 deletions(-) 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..08acbc4688 100644 --- a/test/rdoc/test_rdoc_markup_to_html_crossref.rb +++ b/test/rdoc/test_rdoc_markup_to_html_crossref.rb @@ -1,7 +1,7 @@ # frozen_string_literal: true require_relative 'xref_test_case' -class TestRDocMarkupToHtmlCrossref < XrefTestCase +class RDocMarkupToHtmlCrossrefTest < XrefTestCase def setup super @@ -67,6 +67,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 +163,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