[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

4 files changed, 37 insertions, 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
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