diff options
| -rw-r--r-- | doc/rdoc/markup_reference.rb | 11 | ||||
| -rw-r--r-- | lib/rdoc.rb | 2 | ||||
| -rw-r--r-- | lib/rdoc/markup/pre_process.rb | 17 | ||||
| -rw-r--r-- | lib/rdoc/parser/c.rb | 19 | ||||
| -rw-r--r-- | lib/rdoc/rdoc.rb | 1 | ||||
| -rw-r--r-- | test/rdoc/test_rdoc_markup_pre_process.rb | 28 |
6 files changed, 58 insertions, 20 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 @@ require 'rdoc' # parameter +type+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+. # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats]. # -# ===== Directives for HTML Output -# -# - <tt># :title: _text_</tt>: -# -# - Appears on a line by itself. -# - Specifies the title for the HTML output. -# -# - <tt># :main: _filename_</tt>: -# - Appears on a line by itself. -# - Specifies the HTML file to be displayed first. -# # ===== Directives for Method Documentation # # - <tt># :call-seq:</tt>: 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 diff --git a/lib/rdoc/markup/pre_process.rb b/lib/rdoc/markup/pre_process.rb index 979f2eadae..3270f8ada2 100644 --- a/lib/rdoc/markup/pre_process.rb +++ b/lib/rdoc/markup/pre_process.rb @@ -187,6 +187,14 @@ class RDoc::Markup::PreProcess 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. + + 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 when 'nodoc' then @@ -217,6 +225,15 @@ class RDoc::Markup::PreProcess 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. + + 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 when 'yield', 'yields' then return blankline unless code_object diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 4050d7aa49..8a1bf821ce 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -1097,15 +1097,34 @@ class RDoc::Parser::C < RDoc::Parser # */ # # 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| case directive when 'main' then @options.main_page = param + + warn <<~MSG + The :main: directive is deprecated and will be removed in RDoc 7. + + 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 @options.default_title = param if @options.respond_to? :default_title= + + warn <<~MSG + The :title: directive is deprecated and will be removed in RDoc 7. + + 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 end 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 @@ The internal error was: return [] if file_list.empty? + # This workaround can be removed after the :main: directive is removed original_options = @options.dup @stats.begin_adding 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 @@ contents of a string. 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 @@ contents of a string. 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 @@ contents of a string. 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 |