* lib/rake.rb, lib/rake/*.rb: Upgrade to rake-10.3.2

[fix GH-668]
* test/rake/*.rb: ditto.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@46818 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/rake/dsl_definition.rb

@@ -6,6 +6,9 @@ module Rake
   ##
   # DSL is a module that provides #task, #desc, #namespace, etc.  Use this
   # when you'd like to use rake outside the top level scope.
+  #
+  # For a Rakefile you run from the comamnd line this module is automatically
+  # included.
 
   module DSL
 
@@ -21,14 +24,45 @@ module Rake
 
     private
 
-    # Declare a basic task.
+    # :call-seq:
+    #   task task_name
+    #   task task_name: dependencies
+    #   task task_name, arguments => dependencies
+    #   task task_name, argument[, argument ...], :needs: dependencies
     #
-    # Example:
-    #   task :clobber => [:clean] do
+    # Declare a basic task.  The +task_name+ is always the first argument.  If
+    # the task name contains a ":" it is defined in that namespace.
+    #
+    # The +dependencies+ may be a single task name or an Array of task names.
+    # The +argument+ (a single name) or +arguments+ (an Array of names) define
+    # the arguments provided to the task.
+    #
+    # The task, argument and dependency names may be either symbols or
+    # strings.
+    #
+    # A task with a single dependency:
+    #
+    #   task clobber: %w[clean] do
     #     rm_rf "html"
     #   end
     #
-    def task(*args, &block)
+    # A task with an argument and a dependency:
+    #
+    #   task :package, [:version] => :test do |t, args|
+    #     # ...
+    #   end
+    #
+    # To invoke this task from the command line:
+    #
+    #   $ rake package[1.2.3]
+    #
+    # Alternate definition:
+    #
+    #   task :package, :version, needs: :test do |t, args|
+    #     # ...
+    #   end
+    #
+    def task(*args, &block) # :doc:
       Rake::Task.define_task(*args, &block)
     end
 
@@ -45,7 +79,7 @@ module Rake
     #     end
     #  end
     #
-    def file(*args, &block)
+    def file(*args, &block) # :doc:
       Rake::FileTask.define_task(*args, &block)
     end
 
@@ -61,7 +95,7 @@ module Rake
     # Example:
     #   directory "testdata/doc"
     #
-    def directory(*args, &block)
+    def directory(*args, &block) # :doc:
       result = file_create(*args, &block)
       dir, _ = *Rake.application.resolve_args(args)
       Rake.each_dir_parent(dir) do |d|
@@ -78,9 +112,9 @@ module Rake
     # about it)
     #
     # Example:
-    #   multitask :deploy => [:deploy_gem, :deploy_rdoc]
+    #   multitask deploy: %w[deploy_gem deploy_rdoc]
     #
-    def multitask(*args, &block)
+    def multitask(*args, &block) # :doc:
       Rake::MultiTask.define_task(*args, &block)
     end
 
@@ -88,14 +122,22 @@ module Rake
     # block.  Returns a NameSpace object that can be used to lookup
     # tasks defined in the namespace.
     #
-    # E.g.
+    # Example:
     #
     #   ns = namespace "nested" do
+    #     # the "nested:run" task
     #     task :run
     #   end
     #   task_run = ns[:run] # find :run in the given namespace.
     #
-    def namespace(name=nil, &block)
+    # Tasks can also be defined in a namespace by using a ":" in the task
+    # name:
+    #
+    #   task "nested:test" do
+    #     # ...
+    #   end
+    #
+    def namespace(name=nil, &block) # :doc:
       name = name.to_s if name.kind_of?(Symbol)
       name = name.to_str if name.respond_to?(:to_str)
       unless name.kind_of?(String) || name.nil?
@@ -108,23 +150,22 @@ module Rake
     #
     # Example:
     #  rule '.o' => '.c' do |t|
-    #    sh %{cc -o #{t.name} #{t.source}}
+    #    sh 'cc', '-o', t.name, t.source
     #  end
     #
-    def rule(*args, &block)
+    def rule(*args, &block) # :doc:
       Rake::Task.create_rule(*args, &block)
     end
 
-    # Describe the next rake task.
-    # Duplicate descriptions are discarded.
+    # Describes the next rake task.  Duplicate descriptions are discarded.
     #
     # Example:
     #   desc "Run the Unit Tests"
-    #   task :test => [:build]
-    #     runtests
+    #   task test: [:build]
+    #     # ... run tests
     #   end
     #
-    def desc(description)
+    def desc(description) # :doc:
       Rake.application.last_description = description
     end
 
@@ -142,7 +183,7 @@ module Rake
     # Example:
     #   import ".depend", "my_rules"
     #
-    def import(*fns)
+    def import(*fns) # :doc:
       fns.each do |fn|
         Rake.application.add_import(fn)
       end