Document do task.

README.md

@@ -61,9 +61,10 @@ project, but here are the commonly-used tasks:
 Use `lein help` to see a complete list. `lein help $TASK` shows the
 usage for a specific task.
 
-You can also chain tasks together in a single command by using commas:
+You can also chain tasks together in a single command by using the
+`do` task with comma-separated tasks:
 
-    $ lein clean, test foo.test-core, jar
+    $ lein do clean, test foo.test-core, jar
 
 Most tasks need to be run from somewhere inside a project directory to
 work, but some (`new`, `help`, `search`, `version`, and `repl`) may

doc/PROFILES.md

@@ -92,8 +92,6 @@ Multiple profiles may be executed in series with colons:
 
     $ lein with-profile 1.3:1.4 test :database
 
-A single `with-profile` call does not apply across task comma-chained tasks.
-
 ## Debugging
 
 To see how a given profile affects your project map, use the

src/leiningen/deploy.clj

@@ -18,7 +18,6 @@
 (defn add-auth-interactively [[id settings]]
   (if (or (and (:username settings) (some settings [:password :passphrase
                                                     :private-key-file]))
-          ;; TODO: any other cases where we will never need a password?
           (.startsWith (:url settings) "file://"))
     [id settings]
     (do

src/leiningen/do.clj

@@ -14,8 +14,12 @@
            (conj []))
        (conj-to-last groups arg))))
 
-(defn ^:no-project-needed do
-  "Perform comma-separated tasks in succession."
+(defn ^:no-project-needed ^:higher-order do
+  "Higher-order task to perform other tasks in succession.
+
+Each comma-separated group should be a task name followed by optional arguments.
+
+USAGE: lein do test, compile :all, deploy private-repo"
   [project & args]
   (doseq [[task-name & args] (group-args args)]
     (main/apply-task (main/lookup-alias task-name project) project args)))

src/leiningen/help.clj

@@ -89,7 +89,7 @@
          (binding [*out* *err*]
            (str task-ns "  Problem loading: " (.getMessage e))))))
 
-(defn ^:no-project-needed help
+(defn ^:no-project-needed ^:higher-order help
   "Display a list of tasks or help for a given task.
 
 Also provides readme, faq, tutorial, news, sample, profiles,

src/leiningen/trampoline.clj

@@ -26,7 +26,7 @@
   (spit (System/getProperty "leiningen.trampoline-file")
         (trampoline-command-string command)))
 
-(defn trampoline
+(defn ^:higher-order trampoline
   "Run a task without nesting the project's JVM inside Leiningen's.
 
 Calculates what needs to run in the project's process for the provided
@@ -34,7 +34,7 @@ task and runs it after Leiningen's own JVM process has exited rather
 than as a subprocess of Leiningen's project.
 
 Use this to save memory or to work around things like stdin issues.
-Not compatible with chaining."
+Not compatible with tasks like do that call eval-in-project multiple times."
   [project task-name & args]
   (let [command (promise)]
     (when (:eval-in-leiningen project)

src/leiningen/upgrade.clj

@@ -4,4 +4,6 @@
 ;; This file is only a placeholder. The real upgrade
 ;; implementation can be found in the 'lein' script.
 
-(defn upgrade ([]) ([target-version]))
+(defn upgrade
+  "Upgrade Leiningen to specified version or latest stable."
+  ([]) ([target-version]))

src/leiningen/with_profile.clj

@@ -12,7 +12,7 @@
                       task-name)]
     (main/apply-task task-name project args)))
 
-(defn ^:no-project-needed with-profile
+(defn ^:no-project-needed ^:higher-order with-profile
   "Apply the given task with the profile(s) specified.
 
 Comma-separated profiles may be given to merge profiles and perform the task.