Added long descriptions to tasks for more detailed help messages

lib/thor.rb

@@ -35,6 +35,20 @@ def desc(usage, description, options={})
       end
     end
 
+    # Defines the long description of the next task.
+    #
+    # ==== Parameters
+    # long description<String>
+    #
+    def long_desc(long_description, options={})
+      if options[:for]
+        task = find_and_refresh_task(options[:for])
+        task.long_description = long_description if long_description
+      else
+        @long_desc = long_description
+      end
+    end
+
     # Maps an input to a task. If you define:
     #
     #   map "-T" => "list"
@@ -153,7 +167,8 @@ def task_help(shell, task_name)
       shell.say "  #{banner(task)}"
       shell.say
       class_options_help(shell, nil => task.options.map { |_, o| o })
-      shell.say task.description
+      shell.say "Description:"
+      shell.say task.long_description.gsub(/^/m, '  \0')
     end
 
     # Prints help information for this class.
@@ -205,7 +220,7 @@ def baseclass #:nodoc:
 
       def create_task(meth) #:nodoc:
         if @usage && @desc
-          tasks[meth.to_s] = Thor::Task.new(meth, @desc, @usage, method_options)
+          tasks[meth.to_s] = Thor::Task.new(meth, @desc, @long_desc, @usage, method_options)
           @usage, @desc, @method_options = nil
           true
         elsif self.all_tasks[meth.to_s] || meth.to_sym == :method_missing

lib/thor/group.rb

@@ -241,7 +241,7 @@ def baseclass #:nodoc:
       end
 
       def create_task(meth) #:nodoc:
-        tasks[meth.to_s] = Thor::Task.new(meth, nil, nil, nil)
+        tasks[meth.to_s] = Thor::Task.new(meth, nil, nil, nil, nil)
         true
       end
   end

lib/thor/task.rb

@@ -1,11 +1,11 @@
 class Thor
-  class Task < Struct.new(:name, :description, :usage, :options)
+  class Task < Struct.new(:name, :description, :long_description, :usage, :options)
     FILE_REGEXP = /^#{Regexp.escape(File.dirname(__FILE__))}/
 
     # A dynamic task that handles method missing scenarios.
     class Dynamic < Task
       def initialize(name, options=nil)
-        super(name.to_s, "A dynamically-generated task", name.to_s, options)
+        super(name.to_s, "A dynamically-generated task", name.to_s, name.to_s, options)
       end
 
       def run(instance, args=[])
@@ -17,8 +17,8 @@ def run(instance, args=[])
       end
     end
 
-    def initialize(name, description, usage, options=nil)
-      super(name.to_s, description, usage, options || {})
+    def initialize(name, description, long_description, usage, options=nil)
+      super(name.to_s, description, long_description || description, usage, options || {})
     end
 
     def initialize_copy(other) #:nodoc:
@@ -99,4 +99,4 @@ def handle_no_method_error?(instance, error, caller)
       end
 
   end
-end
+end

spec/fixtures/script.thor

@@ -52,6 +52,10 @@ END
   end
 
   desc "long_description", "a" * 80
+  long_desc <<-HERE_DOC
+This is a really really really long description.
+Here you go. So very long
+  HERE_DOC
   def long_description
   end
 

spec/task_spec.rb

@@ -6,7 +6,7 @@ def task(options={})
       options[key] = Thor::Option.parse(key, value)
     end
 
-    @task ||= Thor::Task.new(:can_has, "I can has cheezburger", "can_has", options)
+    @task ||= Thor::Task.new(:can_has, "I can has cheezburger", "I can has cheezburger\nLots and lots of it", "can_has", options)
   end
 
   describe "#formatted_usage" do
@@ -46,7 +46,7 @@ def task(options={})
 
   describe "#dup" do
     it "dup options hash" do
-      task = Thor::Task.new("can_has", nil, nil, :foo => true, :bar => :required)
+      task = Thor::Task.new("can_has", nil, nil, nil, :foo => true, :bar => :required)
       task.dup.options.delete(:foo)
       task.options[:foo].must_not be_nil
     end

spec/thor_spec.rb

@@ -191,9 +191,10 @@ def shell
 Options:
   [--force]  # Force to do some fooing
 
-do some fooing
-  This is more info!
-  Everyone likes more info!
+Description:
+  do some fooing
+    This is more info!
+    Everyone likes more info!
 END
       end
 
@@ -206,6 +207,10 @@ def shell
       it "normalizes names before claiming they don't exist" do
         capture(:stdout) { MyScript.task_help(shell, "name-with-dashes") }.must =~ /thor my_script:name-with-dashes/
       end
+
+      it "uses the long description if it exists" do
+        capture(:stdout) { MyScript.task_help(shell, "long_description") }.must =~ /really really really long description/
+      end
     end
 
     describe "instance method" do