Refactor RDoc::Task so RDoc::TagsTask can reuse it better

Author: drbrain

History.txt

@@ -3,6 +3,7 @@
 * Minor enhancements
   * RDoc generator authors may now suppress updating the output dir (creating
     a created.rid file) by setting RDoc::Options#update_output_dir to false.
+  * RDoc::Task has been refactored to ease creating subclasses.
 * Bug fixes
   * RDoc's gitignore now ignores .DS_Store files.  Pull Request #3 by Shane
     Becker.

lib/rdoc/task.rb

@@ -149,32 +149,58 @@ class RDoc::Task < Rake::TaskLib
   # Create an RDoc task with the given name. See the RDoc::Task class overview
   # for documentation.
 
-  def initialize(name = :rdoc)  # :yield: self
-    if name.is_a? Hash then
-      invalid_options = name.keys.map { |k| k.to_sym } -
-        [:rdoc, :clobber_rdoc, :rerdoc]
-
-      unless invalid_options.empty? then
-        raise ArgumentError, "invalid options: #{invalid_options.join(", ")}"
-      end
-    end
+  def initialize name = :rdoc # :yield: self
+    defaults
+
+    check_names name
 
     @name = name
+
+    yield self if block_given?
+
+    define
+  end
+
+  ##
+  # Ensures that +names+ only includes names for the :rdoc, :clobber_rdoc and
+  # :rerdoc.  If other names are given an ArgumentError is raised.
+
+  def check_names names
+    return unless Hash === names
+
+    invalid_options =
+      names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]
+
+    unless invalid_options.empty? then
+      raise ArgumentError, "invalid options: #{invalid_options.join ', '}"
+    end
+  end
+
+  ##
+  # Task description for the clobber rdoc task or its renamed equivalent
+
+  def clobber_task_description
+    "Remove RDoc HTML files"
+  end
+
+  ##
+  # Sets default task values
+
+  def defaults
+    @name = :rdoc
     @rdoc_files = Rake::FileList.new
     @rdoc_dir = 'html'
     @main = nil
     @title = nil
     @template = nil
     @generator = nil
     @options = []
-    yield self if block_given?
-    define
   end
 
   ##
   # All source is inline now.  This method is deprecated
 
-  def inline_source() # :nodoc:
+  def inline_source # :nodoc:
     warn "RDoc::Task#inline_source is deprecated"
     true
   end
@@ -190,13 +216,13 @@ def inline_source=(value) # :nodoc:
   # Create the tasks defined by this task lib.
 
   def define
-    desc "Build RDoc HTML files"
+    desc rdoc_task_description
     task rdoc_task_name
 
-    desc "Rebuild RDoc HTML files"
+    desc rerdoc_task_description
     task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
 
-    desc "Remove RDoc HTML files"
+    desc clobber_task_description
     task clobber_task_name do
       rm_r @rdoc_dir rescue nil
     end
@@ -215,11 +241,9 @@ def define
       @before_running_rdoc.call if @before_running_rdoc
       args = option_list + @rdoc_files
 
-      if Rake.application.options.trace then
-        $stderr.puts "rdoc #{args.join ' '}"
-      end
+      $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
       require 'rdoc/rdoc'
-      RDoc::RDoc.new.document(args)
+      RDoc::RDoc.new.document args
     end
 
     self
@@ -247,6 +271,20 @@ def before_running_rdoc(&block)
     @before_running_rdoc = block
   end
 
+  ##
+  # Task description for the rdoc task or its renamed equivalent
+
+  def rdoc_task_description
+    'Build RDoc HTML files'
+  end
+
+  ##
+  # Task description for the rerdoc task or its renamed description
+
+  def rerdoc_task_description
+    "Rebuild RDoc HTML files"
+  end
+
   private
 
   def rdoc_target

test/test_rdoc_task.rb

@@ -6,25 +6,29 @@ class TestRDocTask < MiniTest::Unit::TestCase
 
   def setup
     Rake::Task.clear
+
+    @t = RDoc::Task.new
   end
 
-  def test_inline_source
-    t = RDoc::Task.new
+  def test_clobber_task_description
+    assert_equal 'Remove RDoc HTML files', @t.clobber_task_description
+  end
 
+  def test_inline_source
     _, err = capture_io do
-      assert t.inline_source
+      assert @t.inline_source
     end
 
     assert_equal "RDoc::Task#inline_source is deprecated\n", err
 
     _, err = capture_io do
-      t.inline_source = false
+      @t.inline_source = false
     end
 
     assert_equal "RDoc::Task#inline_source is deprecated\n", err
 
     capture_io do
-      assert t.inline_source
+      assert @t.inline_source
     end
   end
 
@@ -51,6 +55,14 @@ def test_generator_option
     assert_equal %w[-o html -f ri], rdoc_task.option_list
   end
 
+  def test_rdoc_task_description
+    assert_equal 'Build RDoc HTML files', @t.rdoc_task_description
+  end
+
+  def test_rerdoc_task_description
+    assert_equal 'Rebuild RDoc HTML files', @t.rerdoc_task_description
+  end
+
   def test_tasks_creation_with_custom_name_string
     rd = RDoc::Task.new("rdoc_dev")
     assert Rake::Task[:rdoc_dev]
@@ -60,7 +72,14 @@ def test_tasks_creation_with_custom_name_string
   end
 
   def test_tasks_creation_with_custom_name_hash
-    options = { :rdoc => "rdoc", :clobber_rdoc => "rdoc:clean", :rerdoc => "rdoc:force" }
+    options = {
+      :rdoc => "rdoc",
+      :clobber_rdoc => "rdoc:clean",
+      :rerdoc => "rdoc:force"
+    }
+
+    Rake::Task.clear
+
     rd = RDoc::Task.new(options)
     assert Rake::Task[:"rdoc"]
     assert Rake::Task[:"rdoc:clean"]