Deprecate main and title directives (#1218)

* Deprecate :main: directive * Deprecate :title: direcive * Update documentation * Remove :main: directive's usage * Update test cases * Add '.rdoc_options' to suggested alternatives
ruby · Dec 5, 2024 · e2d4ac9 · e2d4ac9
1 parent 09d7f35
commit e2d4ac9
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 20 deletions.
diff --git 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
-#
-# - <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
@@ -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
@@ -187,6 +187,14 @@ 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.
+
+        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 @@ 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.
+
+        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
@@ -1097,15 +1097,34 @@ 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|
       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
@@ -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
 

diff --git 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