[ruby/rdoc] Deprecate `main` and `title` directives

(https://github.com/ruby/rdoc/pull/1218)

* Deprecate :main: directive

* Deprecate :title: direcive

* Update documentation

* Remove :main: directive's usage

* Update test cases

* Add '.rdoc_options' to suggested alternatives

https://github.com/ruby/rdoc/commit/e2d4ac9dad

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