buildr 0.18.0 → 0.19.0

data/lib/core/rake_ext.rb

@@ -0,0 +1,116 @@
+module Rake #:nodoc:
+  class Task
+
+    # Access the base directory. The base directory is set when the class
+    # is defined from the current directory. The current directory is set
+    # to the base directory when the class is executed.
+    attr_accessor :base_dir
+
+    def initialize_with_base_dir(*args) #:nodoc:
+      @base_dir = Dir.pwd
+      initialize_without_base_dir *args
+    end
+    alias_method_chain :initialize, :base_dir
+
+    def invoke #:nodoc:
+      tasks = (Thread.current[:tasks] || [])
+      if tasks.include?(name)
+        fail "Circular dependency " + (tasks + [name]).join("=>")
+      end
+      @lock.synchronize do
+        if application.options.trace
+          puts "** Invoke #{name} #{format_trace_flags}"
+        end
+        return if @already_invoked
+        begin
+          Thread.current[:tasks] = tasks + [name]
+          @already_invoked = true
+          Dir.chdir(@base_dir || Dir.pwd) do
+            invoke_prerequisites
+            execute if needed?
+          end
+        ensure
+          Thread.current[:tasks] = tasks
+        end
+      end
+    end
+
+    def invoke_prerequisites() #:nodoc:
+      prerequisites.each { |n| application[n, @scope].invoke }
+    end
+
+  end
+
+  class Application #:nodoc:
+
+    def in_namespace_with_global_scope(name, &block)
+      if name =~ /^:/
+        begin
+          scope, @scope = @scope, name.split(":")[1...-1]
+          in_namespace_without_global_scope name.split(":").last, &block
+        ensure
+          @scope = scope
+        end
+      else
+        in_namespace_without_global_scope name, &block
+      end
+    end
+    alias_method_chain :in_namespace, :global_scope
+
+  end
+
+  class CheckTask < Rake::Task
+
+    def execute()
+      @warnings = []
+      super
+      report if verbose
+    end
+
+    def note(*msg)
+      @warnings += msg
+    end
+
+    def report()
+      if @warnings.empty?
+        puts HighLine.new.color("No warnings", :green)
+      else
+        warn "These are possible problems with your Rakefile"
+        @warnings.each { |msg| warn "  #{msg}" }
+      end
+    end
+
+  end
+
+
+  desc "Check your Rakefile for common errors"
+  CheckTask.define_task "check"
+
+  # Check for circular dependencies
+  task "check" do
+    # Keep track of tasks we already checked, to avoid death circles.
+    checked = {}
+    # The stack keeps track of all the tasks we visit, so we can display the tasks
+    # involved in the circular dependency.
+    expand = lambda do |stack, task|
+      # Already been here, no need to check again, but make sure we're not seeing
+      # the same task twice due to a circular dependency.
+      fail "Circular " + (stack + [task]).join("=>") if stack.include?(task)
+      unless checked[task]
+        checked[task] = true
+        # Variable task may be a Task, but may also be a task name. In the later
+        # case, we need to resolve it into a Task. But it may also be a filename,
+        # pointing to a file that may exist, just not during the check, so we need
+        # this check to avoid dying on "Don't know how to build ..."
+        if real_task = Rake.application.lookup(task, [])
+          one_deeper = stack + [task.to_s]
+          real_task.prerequisites.each { |prereq| expand[one_deeper, prereq.to_s] }
+        end 
+      end
+    end
+    Rake.application.tasks.each do |task|
+      expand[ [], task.to_s ]
+    end
+  end
+
+end

data/lib/core/transports.rb

@@ -12,46 +12,81 @@ require "highline"
 # Monkeypatching: SFTP never defines the mkdir method on its session or the underlying
 # driver, it just redirect calls through method_missing. Rake, on the other hand, decides
 # to define mkdir on Object, and so routes our calls to FileUtils.
-class Net::SFTP::Session
-  def mkdir(path, attrs = {})
-    method_missing :mkdir, path, attrs
+module Net #:nodoc:all
+  class Session
+    def mkdir(path, attrs = {})
+      method_missing :mkdir, path, attrs
+    end
   end
-end
 
-class Net::SFTP::Protocol::Driver
-  def mkdir(first, path, attrs = {})
-    method_missing :mkdir, first, path, attrs
+  class SFTP::Protocol::Driver
+    def mkdir(first, path, attrs = {})
+      method_missing :mkdir, first, path, attrs
+    end
   end
 end
 
 
 module Buildr
+
+  # Transports are used for downloading artifacts from remote repositories, uploading
+  # artifacts to deployment repositories, and anything else you need to move around.
+  #
+  # The HTTP transport is used for all URLs with the scheme http or https. You can only
+  # use the HTTP transport to download artifacts.
+  #
+  # The SFTP transport is used for all URLs with the schema sftp. You can only use the
+  # SFTP transport to upload artifacts.
+  #
+  # The SFTP transport supports the following options:
+  # * :username -- The username.
+  # * :password -- A password. If unspecified, you will be prompted to enter a password.
+  # * :permissions -- Permissions to set on the uploaded file.
+  # You can also pass the username/password in the URL.
+  #
+  # The SFTP transport will automatically create MD5 and SHA1 digest files for each file
+  # it uploads.
   module Transports
 
+    # Indicates the requested resource was not found.
     class NotFound < Exception
     end
 
-    # Perform one or more operations using an open connection to the
-    # specified URL. For examples, see Transport#download and Transport#upload.
-    def self.perform(url, options = nil, &block)
-      uri = URI.parse(url.to_s)
-      const_get(uri.scheme.upcase).perform(uri, options, &block)
-    end
+    class << self
 
-    # Convenience method for downloading a single file from the specified
-    # URL to the target file.
-    def self.download(url, target, options = nil)
-      uri = URI.parse(url.to_s)
-      path, uri.path = uri.path, ""
-      const_get(uri.scheme.upcase).perform(uri, options) do |transport|
-        transport.download(path, target)
+      # :call-seq:
+      #   perform(url, options?) { |transport| ... }
+      #
+      # Perform one or more operations using an open connection to the
+      # specified URL. For examples, see Transport#download and Transport#upload.
+      def perform(url, options = nil, &block)
+        uri = URI.parse(url.to_s)
+        const_get(uri.scheme.upcase).perform(uri, options, &block)
       end
+
+      # :call-seq:
+      #   download(url, target, options?)
+      #
+      # Convenience method for downloading a single file from the specified
+      # URL to the target file.
+      def download(url, target, options = nil)
+        uri = URI.parse(url.to_s)
+        path, uri.path = uri.path, ""
+        const_get(uri.scheme.upcase).perform(uri, options) do |transport|
+          transport.download(path, target)
+        end
+      end
+
     end
 
+    # Extend this class if you are implementing a new transport.
     class Transport
 
       class << self
 
+        # :call-seq:
+        #   perform(url, options?) { |transport| ... }
+        #
         # Perform one or more operations using an open connection to the
         # specified URL. For examples, see #download and #upload.
         def perform(url, options = nil)
@@ -71,6 +106,7 @@ module Buildr
       # Options passed during construction.
       attr_reader :options
 
+      # Initialize the transport with the specified URL and options.
       def initialize(url, options)
         @uri = URI.parse(url.to_s)
         @base_path = @uri.path || "/"
@@ -138,10 +174,10 @@ module Buildr
           end
           progress_bar.format = "#{truncated}: %3d%% %s %s/%s %s"
           progress_bar.format = "%3d%% %s %s/%s %s"
-          progress_bar.format_arguments = [:percentage, :bar, :bytes, :total, :stat] 
+          progress_bar.format_arguments = [:percentage, :bar, :bytes, :total, :stat]
           progress_bar.bar_mark = "."
 
-       
+
           begin
             class << progress_bar
               def <<(bytes)
@@ -194,7 +230,7 @@ module Buildr
         digester.to_hash
       end
 
-      class Digester
+      class Digester #:nodoc:
 
         def initialize(types)
           types ||= [ "md5", "sha1" ]
@@ -210,7 +246,7 @@ module Buildr
         end
 
         # Iterate over all the digests calling the block with two arguments:
-        # the digest type (e.g. "md5") and the hexadecimal digest value. 
+        # the digest type (e.g. "md5") and the hexadecimal digest value.
         def each()
           @digests.each { |type, digest| yield type, digest.hexdigest }
         end
@@ -228,7 +264,7 @@ module Buildr
     end
 
 
-    class HTTP < Transport
+    class HTTP < Transport #:nodoc:
 
       def initialize(url, options)
         super
@@ -254,7 +290,7 @@ module Buildr
                   response.read_body do |chunk|
                     write[chunk]
                     digester << chunk
-                    progress << chunk 
+                    progress << chunk
                   end
                   # Check server digests before approving the download.
                   digester.each do |type, hexdigest|
@@ -267,7 +303,7 @@ module Buildr
                     end
                   end
                 end
-            
+
                 if target
                   # If download breaks we end up with a partial file which is
                   # worse than not having a file at all, so download to temporary
@@ -297,8 +333,11 @@ module Buildr
 
     end
 
+    # Use the HTTP transport for HTTPS connections.
+    HTTPS = HTTP #:nodoc:
 
-    class SFTP < Transport
+
+    class SFTP < Transport #:nodoc:
 
       class << self
         def passwords()
@@ -310,6 +349,7 @@ module Buildr
 
       def initialize(url, options)
         super
+        @permissions = options.delete :permissions
         # SSH options are based on the username/password from the URI.
         ssh_options = { :port=>@uri.port, :username=>@uri.user }.merge(options || {})
         ssh_options[:password] ||= SFTP.passwords[@uri.host]
@@ -334,30 +374,34 @@ module Buildr
         File.open(source) do |file|
           with_progress_bar path.split("/").last, File.size(source) do |progress|
             with_digests(@options[:digests]) do |digester|
-              puts "Uploading to #{@base_path}#{path}" if Rake.application.options.trace
-              @sftp.open_handle(@base_path + path, "w") do |handle|
+              target_path = "#{@base_path}#{path}"
+              puts "Uploading to #{target_path}" if Rake.application.options.trace
+              @sftp.open_handle(target_path, "w") do |handle|
                 # Writing in chunks gives us the benefit of a progress bar,
                 # but also require that we maintain a position in the file,
                 # since write() with two arguments always writes at position 0.
                 pos = 0
-                while chunk = file.read(32 * 4096) 
+                while chunk = file.read(32 * 4096)
                   @sftp.write(handle, chunk, pos)
                   pos += chunk.size
                   digester << chunk
                   progress << chunk
                 end
               end
+              @sftp.setstat(target_path, :permissions => @permissions) if @permissions
 
               # Upload all the digests.
               digester.each do |type, hexdigest|
-                puts "Uploading signature to #{@base_path}#{path}.#{type}" if Rake.application.options.trace
-                @sftp.open_handle("#{@base_path}#{path}.#{type}", "w") do |handle|
+                digest_file = "#{@base_path}#{path}.#{type}"
+                puts "Uploading signature to #{digest_file}" if Rake.application.options.trace
+                @sftp.open_handle(digest_file, "w") do |handle|
                   @sftp.write(handle, "#{hexdigest}  #{path}")
                 end
+                @sftp.setstat(digest_file, :permissions => @permissions) if @permissions
               end
             end
 
-          end 
+          end
         end
       end
 
@@ -367,8 +411,9 @@ module Buildr
         # otherwise mkdir fails.
         puts "Creating path #{@base_path}" if Rake.application.options.trace
         path.split("/").inject(@base_path) do |base, part|
-          @sftp.realpath(base+part) rescue @sftp.mkdir base + part
-          "#{base}#{part}/"
+          combined = base + part
+          @sftp.realpath combined rescue @sftp.mkdir combined, {}
+          "#{combined}/"
         end
       end
 

data/lib/java/ant.rb

@@ -0,0 +1,78 @@
+require "core/project"
+require "java/java"
+
+module Buildr
+  module Java
+    module Ant
+
+      # Libraries used by #ant.
+      REQUIRES = [ "ant:ant:jar:1.6.5", "ant:ant-launcher:jar:1.6.5", "xerces:xercesImpl:jar:2.6.2" ]
+
+      # Make sure Ant and friends show on the classpath. Antwrap must only be loaded after RJB.
+      Java.rjb.classpath += REQUIRES
+      Java.rjb.onload { require "antwrap" }
+
+      class << self
+
+        # :call-seq:
+        #   declarative(name, options?) => AntProject
+        #   declarative(name, options?) { |AntProject| ... } => AntProject
+        #
+        # Returns a declarative AntProject with the specified name. Ant tasks created in this project
+        # are not executed until you tell them to.
+        #
+        # See #ant for more information about options and the block.
+        def declarative(name, options = nil, &block)
+          options ||= {}
+          options = (options || {}).merge(:name=>name, :base_dir=>Dir.pwd, :declarative=>false)
+          Java.rjb { AntProject.new(options).tap { |project| yield project if block_given? } }
+        end
+
+        # :call-seq:
+        #   executable(name, options?) => AntProject
+        #   executable(name, options?) { |AntProject| ... } => AntProject
+        #
+        # Returns an executable AntProject with the specified name. Ant tasks created in this project
+        # are executed immediately.
+        #
+        # See #ant for more information about options and the block.
+        def executable(name, options = nil, &block)
+          options ||= {}
+          options = (options || {}).merge(:name=>name, :base_dir=>Dir.pwd, :declarative=>true)
+          Java.rjb { AntProject.new(options).tap { |project| yield project if block_given? } }
+        end
+      end
+
+      # :call-seq:
+      #   ant(name, options?) => AntProject
+      #   ant(name, options?) { |AntProject| ... } => AntProject
+      #
+      # Returns a new AntProject with the specified name. Ant tasks created in this project are
+      # executed immediately.
+      #
+      # The options hash is passed to the Ant project definition, along with the current directory.
+      # When used in a Buildr project, the Ant project will have the same base directory.
+      # If you pass a block, yields to the block with the Ant project.
+      #
+      # For example:
+      #   ant("hibernatedoclet") do |doclet|
+      #     doclet.taskdef :name=>"hibernatedoclet",
+      #       :classname=>"xdoclet.modules.hibernate.HibernateDocletTask", :classpath=>DOCLET
+      #     doclet.hibernatedoclet :destdir=>dest_dir, :force=>"true" do
+      #       hibernate :version=>"3.0"
+      #       fileset :dir=>source, :includes=>"**/*.java"
+      #     end
+      #   end
+      def ant(name, options=nil, &block)
+        Java::Ant.executable(name, options, &block)
+      end
+
+    end
+
+  end
+
+  class Project
+    include Java::Ant
+  end
+
+end

data/lib/{core → java}/artifact.rb

@@ -1,16 +1,25 @@
+require "core/project"
+require "core/transports"
+
 module Buildr
 
   desc "Download all artifacts"
   task "artifacts"
 
-  # This module gives you a way to access the individual properties of an
-  # artifact: id, group, type, classifier and version. It also provides other
-  # methods commonly used on an artifact, specifically #to_hash and #to_spec.
+  # Mixin with a task to make it behave like an artifact. Implemented by the packaging tasks.
+  #
+  # An artifact has an identifier, group identifier, type, version number and
+  # optional classifier. All can be used to locate it in the local repository,
+  # download from or upload to a remote repository.
+  #
+  # The #to_spec and #to_hash methods allow it to be used everywhere an artifact is
+  # accepted.
   module ActsAsArtifact
 
     ARTIFACT_ATTRIBUTES = [:group, :id, :type, :classifier, :version]
 
     class << self
+    private
       def included(mod)
         mod.extend self
       end
@@ -27,21 +36,44 @@ module Buildr
     # Optional artifact classifier.
     attr_reader :classifier
 
-    # Returns the artifact specification as a hash.
+    # :call-seq:
+    #   to_spec_hash() => Hash
+    #
+    # Returns the artifact specification as a hash. For example:
+    #   com.example:app:jar:1.2
+    # becomes:
+    #   { :group=>"com.example",
+    #     :id=>"app",
+    #     :type=>"jar",
+    #     :version=>"1.2" }
     def to_spec_hash()
       base = { :group=>group, :id=>id, :type=>type, :version=>version }
       classifier.blank? ? base : base.merge(:classifier=>classifier)
     end
     alias_method :to_hash, :to_spec_hash
 
+    # :call-seq:
+    #   to_spec() => String
+    #
     # Returns the artifact specification, in the structure:
     #   <group>:<artifact>:<type>:<version>
     # or
-    #   <group>:<artifact>:<type>:<classifier><:<version>
+    #   <group>:<artifact>:<type>:<classifier><:version>
     def to_spec()
       classifier.blank? ? "#{group}:#{id}:#{type}:#{version}" : "#{group}:#{id}:#{type}:#{classifier}:#{version}"
     end
 
+    # :call-seq:
+    #   pom() => Artifact
+    # 
+    # Convenience method that returns a POM artifact.
+    def pom()
+      return self if type.to_s == "pom"
+      artifact(:group=>group, :id=>id, :version=>version, :type=>"pom", :classifier=>classifier)
+    end
+
+  protected
+
     # Apply specification to this artifact.
     def apply_spec(spec)
       spec = Artifact.to_hash(spec)
@@ -49,20 +81,17 @@ module Buildr
       self
     end
 
-    # Convenience method that returns a POM artifact.
-    def pom()
-      return self if type.to_s == "pom"
-      artifact(:group=>group, :id=>id, :version=>version, :type=>"pom", :classifier=>classifier)
-    end
-
   end
 
-
-  # The Artifact task maps to an artifact file in the local repository
-  # and knows how to download the file from a remote repository.
+ 
+  # A file task referencing an artifact in the local repository.
+  #
+  # This task includes all the artifact attributes (group, id, version, etc). It points
+  # to the artifact's path in the local repository. When invoked, it will download the
+  # artifact into the local repository if the artifact does not already exist.
   #
-  # The task will only download the file if it does not exist. You can
-  # enhance the task to create the artifact yourself.
+  # Note: You can enhance this task to create the artifact yourself, e.g. download it from
+  # a site that doesn't have a remote repository structure, copy it from a different disk, etc.
   class Artifact < Rake::FileCreationTask
 
     # The default file type for artifacts, if not specified.
@@ -72,37 +101,44 @@ module Buildr
 
     class << self
 
-      # Lookup a previously registered artifact task based on the
-      # artifact specification (string or hash).
+      # :call-seq:
+      #   lookup(spec) => Artifact
+      #
+      # Lookup a previously registered artifact task based on its specification (String or Hash).
       def lookup(spec)
         @artifacts ||= {}
         @artifacts[to_spec(spec)]
       end
 
+      # :call-seq:
+      #   register(artifacts) => artifacts
+      #
       # Register an artifact task(s) for later lookup (see #lookup).
       def register(*tasks)
         @artifacts ||= {}
-        fail "You can only register an artifact task, strings and hashes are just not good enough" unless
+        fail "You can only register an artifact task, one of the arguments is not a Task that responds to to_spec()" unless
           tasks.all? { |task| task.respond_to?(:to_spec) && task.respond_to?(:invoke) }
         tasks.each { |task| @artifacts[task.to_spec] = task }
         tasks
       end
 
-      # Turn a spec into a hash. This method accepts a string, hash or any object
-      # that responds to the method to_spec. There are several reasons to use this
-      # method:
+      # :call-seq:
+      #   to_hash(spec_hash) => spec_hash
+      #   to_hash(spec_string) => spec_hash
+      #   to_hash(artifact) => spec_hash
+      #
+      # Turn a spec into a hash. This method accepts a String, Hash or any object that responds to
+      # the method to_spec. There are several reasons to use this method:
       # * You can pass anything that could possibly be a spec, and get a hash.
       # * It will check that the spec includes the group identifier, artifact
       #   identifier and version number and set the file type, if missing.
       # * It will always return a new specs hash.
-      #
-      # :nodoc:
       def to_hash(spec)
         if spec.respond_to?(:to_spec)
           to_hash spec.to_spec
         elsif Hash === spec
           # Sanitize the hash and check it's valid.
-          spec = ARTIFACT_ATTRIBUTES.inject({}) { |h, k| h[k] = spec[k] ; h }
+          spec = ARTIFACT_ATTRIBUTES.inject({}) { |h, k| h[k] = spec[k].to_s if spec[k] ; h }
           fail "Missing group identifier for #{spec.inspect}" if spec[:group].blank?
           fail "Missing artifact identifier for #{spec.inspect}" if spec[:id].blank?
           fail "Missing version for #{spec.inspect}" if spec[:version].blank?
@@ -121,9 +157,11 @@ module Buildr
         end
       end
 
+      # :call-seq:
+      #   to_spec(spec_hash) => spec_string
+      #
       # Convert a hash back to a spec string. This method accepts
       # a string, hash or any object that responds to to_spec.
-      # :nodoc:
       def to_spec(hash)
         hash = to_hash(hash) unless Hash === hash
         version = ":#{hash[:version]}" unless hash[:version].blank?
@@ -131,8 +169,10 @@ module Buildr
         "#{hash[:group]}:#{hash[:id]}:#{hash[:type] || DEFAULT_FILE_TYPE}#{classifier}#{version}"
       end
 
-      # Convert a hash to a file name.
-      # :nodoc:
+      # :call-seq:
+      #   hash_to_file_name(spec_hash) => file_name
+      #
+      # Convert a hash spec to a file name.
       def hash_to_file_name(hash)
         version = "-#{hash[:version]}" unless hash[:version].blank?
         classifier = "-#{hash[:classifier]}" unless hash[:classifier].blank?
@@ -141,15 +181,20 @@ module Buildr
 
     end
 
-    def execute()
-      # Default behavior: download the artifact from one of the remote
-      # repositories if the file does not exist. But this default behavior
-      # is counter useful if the artifact knows how to build itself
-      # (e.g. download from a different location), so don't perform it
-      # if the task found a different way to create the artifact.
+    def initialize(*args) #:nodoc:
       super
-      unless Rake.application.options.dryrun || File.exist?(name)
-        repositories.download(to_spec)
+      enhance do |task|
+        # Default behavior: download the artifact from one of the remote
+        # repositories if the file does not exist. But this default behavior
+        # is counter useful if the artifact knows how to build itself
+        # (e.g. download from a different location), so don't perform it
+        # if the task found a different way to create the artifact.
+        # For that, we need to be the last piece of code run by the task.
+        task.enhance do
+          unless Rake.application.options.dryrun || File.exist?(name)
+            repositories.download(to_spec)
+          end
+        end
       end
     end
 
@@ -158,25 +203,41 @@ module Buildr
 
   # Holds the path to the local repository, URLs for remote repositories, and
   # settings for the deployment repository.
+  #
+  # You can access this object from the #repositories method. For example:
+  #   puts repositories.local
+  #   repositories.remote << "http://example.com/repo"
+  #   repositories.deploy_to = "sftp://example.com/var/www/public/repo"
   class Repositories
     include Singleton
 
+    # :call-seq:
+    #   local() => path
+    #
     # Returns the path to the local repository.
     #
     # The default path is .m2/repository relative to the home directory.
-    # You can change the location of the local repository by using a symbol
-    # link or by setting a different path. If you set a different path, do it
-    # in the buildr.rb file instead of the Rakefile. 
     def local()
-      @local ||= ENV["local_repo"] || File.join(ENV["HOME"], ".m2", "repository")
+      @local ||= ENV["local_repo"] || File.join(ENV["HOME"], ".m2/repository")
     end
 
+    # :call-seq:
+    #   local = path
+    #
     # Sets the path to the local repository.
+    #
+    # The best place to set the local repository path is from a buildr.rb file
+    # located in your home directory. That way all your projects will share the same
+    # path, without affecting other developers collaborating on these projects.
     def local=(dir)
       @local = dir ? File.expand_path(dir) : nil
     end
 
-    # Locates an artifact in the local repository based on its specification.
+    # :call-seq:
+    #   locate(spec) => path
+    #
+    # Locates an artifact in the local repository based on its specification, and returns
+    # a file path.
     #
     # For example:
     #   locate :group=>"log4j", :id=>"log4j", :version=>"1.1"
@@ -186,16 +247,28 @@ module Buildr
       File.join(local, spec[:group].split("."), spec[:id], spec[:version], Artifact.hash_to_file_name(spec))
     end
 
-    # Returns an array of all the remote repositories. When downloading an artifact,
-    # the default behavior is to try repositories in the order in which they show in
-    # the array.
+    # :call-seq:
+    #   remote() => Array
+    #
+    # Returns an array of all the remote repository URLs.
+    #
+    # When downloading artifacts, repositories are accessed in the order in which they appear here.
+    # The best way is to add repositories individually, for example:
+    #   repositories.remote << "http://example.com/repo"
     def remote()
       @remote ||= []
     end
 
-    # With a string argument, sets the remote repository (only one) to this URL.
-    # With an array argument, sets the remote repository to that set of URLs.
-    # Passing nil is equivalent to an empty array.
+    # :call-seq:
+    #   remote = Array
+    #   remote = url
+    #   remote = nil
+    #
+    # With a String argument, clears the array and set it to that single URL.
+    #
+    # With an Array argument, clears the array and set it to these specific URLs.
+    #
+    # With nil, clears the array.
     def remote=(urls)
       case urls
       when nil
@@ -207,9 +280,18 @@ module Buildr
       end
     end
 
-    # Attempts to download the artifact from one of the remote repositories
-    # and store it in the local repository. Returns the path if downloaded,
-    # otherwise raises an exception.
+   
+    # :call-seq:
+    #   download(spec) => boolean
+    # 
+    # Downloads an artifact from one of the remote repositories, and stores it in the local
+    # repository. Accepts a String or Hash artifact specification, and returns a path to the
+    # artifact in the local repository. Raises an exception if the artifact is not found.
+    #
+    # This method attempts to download the artifact from each repository in the order in
+    # which they are returned from #remote, until successful. If you want to download an
+    # artifact only if not already installed in the local repository, create an #artifact
+    # task and invoke it directly.
     def download(spec)
       spec = Artifact.to_hash(spec) unless Hash === spec
       path = locate(spec)
@@ -236,27 +318,38 @@ module Buildr
       fail "Failed to download #{Artifact.to_spec(spec)}, tried the following repositories:\n#{repositories.remote.join("\n")}"
     end
 
-    # Specifies the deployment repository. Accepts a hash with the different
-    # repository settings (e.g. url, username, password). Anything else is
-    # interepted as the URL.
+    # :call-seq:
+    #   deploy_to = url
+    #   deploy_to = hash
+    #
+    # Specifies the deployment repository. Accepts a Hash with different repository settings
+    # (e.g. url, username, password), or a String to only set the repository URL.
+    #
+    # Besides the URL, all other settings depend on the transport protocol in use. See #Transports
+    # for more details. Common settings include username and password.
     #
     # For example:
-    #   repositories.deploy_to = { :url=>"sftp://example.com/var/www/maven/",
+    #   repositories.deploy_to = { :url=>"sftp://example.com/var/www/repo/",
     #                              :username="john", :password=>"secret" }
     # or:
-    #   repositories.deploy_to = "sftp://john:secret@example.com/var/www/maven/"
+    #   repositories.deploy_to = "sftp://john:secret@example.com/var/www/repo/"
     def deploy_to=(options)
       options = { :url=>options } unless Hash === options
       @deploy_to = options
     end
 
-    # Returns the current deployment repository configuration. This is a more
-    # convenient way to specify deployment in the Rakefile, and override it
-    # locally. For example:
-    #   # Rakefile
-    #   repositories.deploy_to[:url] ||= "sftp://example.com"
-    #   # buildr.rb
-    #   repositories.deploy_to[:url] = "sftp://acme.org"
+    # :call-seq:
+    #   deploy_to() => hash
+    #
+    # Returns the current deployment repository setting as a Hash. This is a more convenient
+    # way to specify the deployment repository, as it allows you to specify the settings
+    # progressively.
+    #
+    # For example, the Rakefile will contain the repository URL used by all developers:
+    #   repositories.deploy_to[:url] ||= "sftp://example.com/var/www/repo"
+    # Your private buildr.rb will contain your credentials:
+    #   repositories.deploy_to[:username] = "john"
+    #   repositories.deploy_to[:password] = "secret"
     def deploy_to()
       @deploy_to ||= {}
     end
@@ -264,94 +357,99 @@ module Buildr
   end
 
 
-  # Returns a global object for setting local, remote and deploy repositories.
+  # :call-seq:
+  #    repositories() => Repositories
+  #
+  # Returns an object you can use for setting the local repository path, remote repositories
+  # URL and deployment repository settings.
+  #
   # See Repositories.
   def repositories()
     Repositories.instance
   end
 
-  # Creates a file task to download and install the specified artifact.
+  # :call-seq:
+  #   artifact(spec) => Artifact
+  #   artifact(spec) { |task| ... } => Artifact
+  #
+  # Creates a file task to download and install the specified artifact in the local repository.
   #
-  # The artifact specification can be a string or a hash.
-  # The file task points to the artifact in the local repository.
+  # You can use a String or a Hash for the artifact specification. The file task will point at
+  # the artifact's path inside the local repository. You can then use this tasks as a prerequisite
+  # for other tasks.
   #
-  # You can provide alternative behavior to create the artifact instead
-  # of downloading it from a remote repository.
+  # This task will download and install the artifact only once. In fact, it will download and
+  # install the artifact if the artifact does not already exist. You can enhance it if you have
+  # a different way of creating the artifact in the local repository. See Artifact for more details.
   #
   # For example, to specify an artifact:
   #   artifact("log4j:log4j:jar:1.1")
   #
   # To use the artifact in a task:
-  #   unzip artifact("org.apache.pxe:db-derby:zip:1.2")
+  #   compile.with artifact("log4j:log4j:jar:1.1")
   #
   # To specify an artifact and the means for creating it:
   #   download(artifact("dojo:dojo-widget:zip:2.0")=>
   #     "http://download.dojotoolkit.org/release-2.0/dojo-2.0-widget.zip")
-  def artifact(spec, &block)
+  def artifact(spec, &block) #:yields:task
     spec = Artifact.to_hash(spec)
     unless task = Artifact.lookup(spec)
       task = Artifact.define_task(repositories.locate(spec))
+      task.send :apply_spec, spec
       Rake::Task["rake:artifacts"].enhance [ task ]
       Artifact.register(task)
     end
-    task.apply_spec spec
     task.enhance &block
   end
 
-  # Creates multiple artifacts from a set of specifications and returns
-  # an array of tasks.
+  # :call-seq:
+  #   artifacts(*spec) => artifacts
+  #
+  # Handles multiple artifacts at a time. This method is the plural equivalent of
+  # #artifacts, but can do more things.
   #
   # You can pass any number of arguments, each of which can be:
-  # * An artifact specification, string or hash. Returns a new task for
-  #   each specification, by calling #artifact.
-  # * An artifact task or any other task. Returns the task as is.
-  # * A project. Returns all packaging tasks in that project.
-  # * An array of artifacts. Returns all the artifacts found there.
+  # * An artifact specification (String or Hash). Returns the appropriate Artifact task.
+  # * An artifact of any other task. Returns the task as is.
+  # * A project. Returns all artifacts created (packaged) by that project.
+  # * A string. Returns that string, assumed to be a file name.
+  # * An array of artifacts. Calls #artifacts on the array, flattens the result.
   #
-  # This method handles arrays of artifacts as if they are flattend,
-  # to help in managing large combinations of artifacts. For example:
+  # For example, handling a collection of artifacts:
   #   xml = [ xerces, xalan, jaxp ]
   #   ws = [ axis, jax-ws, jaxb ]
   #   db = [ jpa, mysql, sqltools ]
-  #   base = [ xml, ws, db ]
-  #   artifacts(base, models, services)
-  #
-  # You can also pass tasks and project. This is particularly useful for
-  # dealing with dependencies between projects that are part of the same
-  # build.
-  #
-  # For example:
-  #   artifacts(base, models, services, module1, module2)
+  #   artifacts(xml, ws, db)
   #
-  # When passing a project as argument, it expands that project to all
-  # its packaging tasks. You can then use the resulting artifacts as
-  # dependencies that will force these packages to be build inside the
-  # project, without installing them in the local repository.
+  # Using artifacts created by a project:
+  #   artifact project("my-app")               # All packages
+  #   artifact project("mu-app").package(:war) # Only the WAR
   def artifacts(*specs)
     specs.inject([]) do |set, spec|
       case spec
+      when Array
+        set |= artifacts(*spec)
       when Hash
         set |= [artifact(spec)]
-      when /:/
+      when /([^:]+:){2,4}/ # A spec as opposed to a file name.
         set |= [artifact(spec)]
-      when String
+      when String # Must always expand path.
         set |= [File.expand_path(spec)]
       when Project
         set |= artifacts(spec.packages)
       when Rake::Task
         set |= [spec]
-      when Array
-        set |= artifacts(*spec)
       else
-        fail "Invalid artifact specification: #{spec.to_s || 'nil'}"
+        fail "Invalid artifact specification in: #{specs.inspect}"
       end
-      set
     end
   end
 
-  # Convenience method for defining multiple artifacts that belong
-  # to the same version and group. Accepts multiple artifact identifiers
-  # (or arrays of) followed by two has keys:
+  # :call-seq:
+  #   groups(ids, :under=>group_name, :version=>number) => artifacts
+  #
+  # Convenience method for defining multiple artifacts that belong to the same group and version.
+  # Accepts multiple artifact identifiers follows by two hash values:
   # * :under -- The group identifier
   # * :version -- The version number
   #
@@ -364,27 +462,32 @@ module Buildr
     args.flatten.map { |id| artifact :group=>hash[:under], :version=>hash[:version], :id=>id }
   end 
 
-  # Deploys all the specified artifacts/files. Specify the deployment
-  # server by passing a hash as the last argument, or have it use
-  # repositories.deploy_to.
+  # :call-seq:
+  #   deploy(*files)
+  #   deploy(*files, deploy_options)
+  #
+  # Deploys all the specified artifacts/files. If the last argument is a Hash, it is used to
+  # specify the deployment repository. Otherwise, obtains the deployment repository by calling
+  # Repositories#deploy_to.
   #
   # For example:
-  #   deploy(*process.packages, :url=>"sftp://example.com/var/www/maven")
+  #   deploy(foo.packages, :url=>"sftp://example.com/var/www/repo")
   def deploy(*args)
     # Where do we release to?
     if Hash === args.last
       options = args.pop
     else
-      options = repositories.deploy_to
+      options = repositories.deploy_to.clone
       options = { :url=>options.to_s } unless Hash === options
     end
+    # Strip all options since the transport requires them separately from the URL.
     url = options[:url]
     options = options.reject { |k,v| k === :url }
     fail "Don't know where to deploy, perhaps you forgot to set repositories.deploy_to" if url.blank?
 
-    args.each { |arg| arg.invoke if arg.respond_to?(:invoke) }
+    args.flatten.each { |arg| arg.invoke if arg.respond_to?(:invoke) }
     Transports.perform url, options do |session|
-      args.each do |artifact|
+      args.flatten.each do |artifact|
         if artifact.respond_to?(:to_spec)
           # Upload artifact relative to base URL, need to create path before uploading.
           puts "Deploying #{artifact.to_spec}" if verbose