From 96b3e01fcf08296364d4e45c1f186d65c4366255 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 29 Nov 2024 22:19:29 +0000 Subject: [PATCH 1/6] Deprecate :main: directive --- lib/rdoc/markup/pre_process.rb | 6 ++++++ lib/rdoc/parser/c.rb | 7 +++++++ lib/rdoc/rdoc.rb | 1 + 3 files changed, 14 insertions(+) diff --git a/lib/rdoc/markup/pre_process.rb b/lib/rdoc/markup/pre_process.rb index 979f2eadae..2ae64d2b1b 100644 --- a/lib/rdoc/markup/pre_process.rb +++ b/lib/rdoc/markup/pre_process.rb @@ -187,6 +187,12 @@ def handle_directive prefix, directive, param, code_object = nil, include_file filename, prefix, encoding when 'main' then @options.main_page = param if @options.respond_to? :main_page + warn <<~MSG + The :main: directive is deprecated and will be removed in RDoc 7. + + Use `--main=#{param}` to specify the initial page displayed. + If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead. + MSG blankline when 'nodoc' then diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 4050d7aa49..04263afa0c 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -1103,6 +1103,13 @@ def look_for_directives_in context, comment case directive when 'main' then @options.main_page = param + + warn <<~MSG + The :main: directive is deprecated and will be removed in RDoc 7. + + Use `--main=#{param}` to specify the initial page displayed. + If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead. + MSG '' when 'title' then @options.default_title = param if @options.respond_to? :default_title= diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb index a910215ff6..0276d430a9 100644 --- a/lib/rdoc/rdoc.rb +++ b/lib/rdoc/rdoc.rb @@ -407,6 +407,7 @@ def parse_files files return [] if file_list.empty? + # This workaround can be removed after the :main: directive is removed original_options = @options.dup @stats.begin_adding From 902c893fa3d184064312c6c1aa48640630d849c4 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 29 Nov 2024 22:20:42 +0000 Subject: [PATCH 2/6] Deprecate :title: direcive --- lib/rdoc/markup/pre_process.rb | 7 +++++++ lib/rdoc/parser/c.rb | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/lib/rdoc/markup/pre_process.rb b/lib/rdoc/markup/pre_process.rb index 2ae64d2b1b..6a6fed7351 100644 --- a/lib/rdoc/markup/pre_process.rb +++ b/lib/rdoc/markup/pre_process.rb @@ -223,6 +223,13 @@ def handle_directive prefix, directive, param, code_object = nil, when 'title' then @options.default_title = param if @options.respond_to? :default_title= + warn <<~MSG + The :title: directive is deprecated and will be removed in RDoc 7. + + Use `--title=#{param}` to specify the title displayed. + If you use `RDoc::Task`, use `rdoc.title = "#{param}"` instead. + MSG + blankline when 'yield', 'yields' then return blankline unless code_object diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 04263afa0c..632bd3ff0c 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -1113,6 +1113,13 @@ def look_for_directives_in context, comment '' when 'title' then @options.default_title = param if @options.respond_to? :default_title= + + warn <<~MSG + The :title: directive is deprecated and will be removed in RDoc 7. + + Use `--title=#{param}` to specify the title displayed. + If you use `RDoc::Task`, use `rdoc.title = "#{param}"` instead. + MSG '' end end From 274fdc324da2f99e6536917651450b8b176f5861 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 29 Nov 2024 22:22:22 +0000 Subject: [PATCH 3/6] Update documentation --- doc/rdoc/markup_reference.rb | 11 ----------- lib/rdoc/parser/c.rb | 1 + 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index bb2dc67eca..defa9f66c9 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -535,17 +535,6 @@ # parameter +type+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+. # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats]. # -# ===== Directives for HTML Output -# -# - # :title: _text_: -# -# - Appears on a line by itself. -# - Specifies the title for the HTML output. -# -# - # :main: _filename_: -# - Appears on a line by itself. -# - Specifies the HTML file to be displayed first. -# # ===== Directives for Method Documentation # # - # :call-seq:: diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 632bd3ff0c..0904e6526d 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -1097,6 +1097,7 @@ def load_variable_map map_name # */ # # This method modifies the +comment+ + # Both :main: and :title: directives are deprecated and will be removed in RDoc 7. def look_for_directives_in context, comment @preprocess.handle comment, context do |directive, param| From 964d39475470d15a19d7cea1af3d00ee6c41e401 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 29 Nov 2024 22:26:40 +0000 Subject: [PATCH 4/6] Remove :main: directive's usage --- lib/rdoc.rb | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/rdoc.rb b/lib/rdoc.rb index 3821569f45..b42059c712 100644 --- a/lib/rdoc.rb +++ b/lib/rdoc.rb @@ -1,8 +1,6 @@ # frozen_string_literal: true $DEBUG_RDOC = nil -# :main: README.rdoc - ## # RDoc produces documentation for Ruby source files by parsing the source and # extracting the definition for classes, modules, methods, includes and From de3ced4ea99ea22bdb11512c907899cc7e26df67 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 29 Nov 2024 22:31:59 +0000 Subject: [PATCH 5/6] Update test cases --- test/rdoc/test_rdoc_markup_pre_process.rb | 28 +++++++++++++++++------ 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/test/rdoc/test_rdoc_markup_pre_process.rb b/test/rdoc/test_rdoc_markup_pre_process.rb index cc5bdc3abf..2a8cd92dd0 100644 --- a/test/rdoc/test_rdoc_markup_pre_process.rb +++ b/test/rdoc/test_rdoc_markup_pre_process.rb @@ -2,7 +2,7 @@ require_relative 'helper' -class TestRDocMarkupPreProcess < RDoc::TestCase +class RDoc::Markup::PreProcessTest < RDoc::TestCase def setup super @@ -85,18 +85,26 @@ def test_include_file_in_other_directory def test_handle text = "# :main: M\n" - out = @pp.handle text + output = nil + _, err = capture_output do + output = @pp.handle text + end - assert_equal "#\n", out + assert_include err, "The :main: directive is deprecated and will be removed in RDoc 7." + assert_equal "#\n", output end def test_handle_comment text = "# :main: M\n" c = comment text - out = @pp.handle c + output = nil + _, err = capture_output do + output = @pp.handle c + end - assert_equal "#\n", out + assert_include err, "The :main: directive is deprecated and will be removed in RDoc 7." + assert_equal "#\n", output end def test_handle_markup @@ -245,8 +253,11 @@ def test_handle_directive_include def test_handle_directive_main @pp.options = RDoc::Options.new - @pp.handle_directive '', 'main', 'M' + _, err = capture_output do + @pp.handle_directive '', 'main', 'M' + end + assert_include err, "The :main: directive is deprecated and will be removed in RDoc 7." assert_equal 'M', @pp.options.main_page end @@ -385,8 +396,11 @@ def test_handle_directive_stopdoc def test_handle_directive_title @pp.options = RDoc::Options.new - @pp.handle_directive '', 'title', 'T' + _, err = capture_output do + @pp.handle_directive '', 'title', 'T' + end + assert_include err, "The :title: directive is deprecated and will be removed in RDoc 7." assert_equal 'T', @pp.options.title end From 83a356185b0dc8e14801d9e28e2f49dc39803f07 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Mon, 2 Dec 2024 12:02:01 +0000 Subject: [PATCH 6/6] Add '.rdoc_options' to suggested alternatives --- lib/rdoc/markup/pre_process.rb | 12 ++++++++---- lib/rdoc/parser/c.rb | 12 ++++++++---- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/lib/rdoc/markup/pre_process.rb b/lib/rdoc/markup/pre_process.rb index 6a6fed7351..3270f8ada2 100644 --- a/lib/rdoc/markup/pre_process.rb +++ b/lib/rdoc/markup/pre_process.rb @@ -190,8 +190,10 @@ def handle_directive prefix, directive, param, code_object = nil, warn <<~MSG The :main: directive is deprecated and will be removed in RDoc 7. - Use `--main=#{param}` to specify the initial page displayed. - If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead. + You can use these options to specify the initial page displayed instead: + - `--main=#{param}` via the command line + - `rdoc.main = "#{param}"` if you use `RDoc::Task` + - `main_page: #{param}` in your `.rdoc_options` file MSG blankline @@ -226,8 +228,10 @@ def handle_directive prefix, directive, param, code_object = nil, warn <<~MSG The :title: directive is deprecated and will be removed in RDoc 7. - Use `--title=#{param}` to specify the title displayed. - If you use `RDoc::Task`, use `rdoc.title = "#{param}"` instead. + You can use these options to specify the title displayed instead: + - `--title=#{param}` via the command line + - `rdoc.title = "#{param}"` if you use `RDoc::Task` + - `title: #{param}` in your `.rdoc_options` file MSG blankline diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 0904e6526d..8a1bf821ce 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -1108,8 +1108,10 @@ def look_for_directives_in context, comment warn <<~MSG The :main: directive is deprecated and will be removed in RDoc 7. - Use `--main=#{param}` to specify the initial page displayed. - If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead. + You can use these options to specify the initial page displayed instead: + - `--main=#{param}` via the command line + - `rdoc.main = "#{param}"` if you use `RDoc::Task` + - `main_page: #{param}` in your `.rdoc_options` file MSG '' when 'title' then @@ -1118,8 +1120,10 @@ def look_for_directives_in context, comment warn <<~MSG The :title: directive is deprecated and will be removed in RDoc 7. - Use `--title=#{param}` to specify the title displayed. - If you use `RDoc::Task`, use `rdoc.title = "#{param}"` instead. + You can use these options to specify the title displayed instead: + - `--title=#{param}` via the command line + - `rdoc.title = "#{param}"` if you use `RDoc::Task` + - `title: #{param}` in your `.rdoc_options` file MSG '' end