From 1c7bbe6db67034535ed679e54af7e442f50715b5 Mon Sep 17 00:00:00 2001
From: Cedric Beust <cedric@beust.com>
Date: Fri, 9 Oct 2015 21:05:42 -0700
Subject: [PATCH] Dynamic tasks and wrapAfter.

---
 plug-in-development/index.html | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/plug-in-development/index.html b/plug-in-development/index.html
index f3e2915..22900b5 100644
--- a/plug-in-development/index.html
+++ b/plug-in-development/index.html
@@ -362,7 +362,7 @@ public fun myConfig(project: Project, init: Info.() -> Unit) : Info {
 </p>
 <h3 class="section" indent="1">Static tasks</h3>
 <p>
-    Static tasks are functions declared directly on your plug-in and annotated with the <code>@Task</code> annotation. Here is an example:
+    Static tasks are functions declared directly in your plug-in class and annotated with the <code>@Task</code> annotation. Here is an example:
 </p>
 <pre>
 @Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
@@ -391,8 +391,34 @@ fun lineCount(project: Project): TaskResult {
           <dd>A list of all the tasks that this task should run prior to.</dd>
           <dt>runAfter</dt>
           <dd>A list of all the tasks that should run before this task does.</dd>
+          <dt>wrapAfter</dt>
+          <dd>A list of all the tasks that will always be run after this task if it's invoked.</dd>
     </dl>
 </p>
+<p>
+    The difference between <code>runAfter</code> and <code>wrapAfter</code> is subtle but important. <code>runAfter</code>
+    is just a declaration of dependency. It's basically the reverse of <code>runBefore</code> but it's useful in case
+    you are not the author of the task you want to run before (if you were, you would just use the <code>runBefore</code>
+    annotation on it). Since you can't say <code>"a runBefore b"</code> because you don't own task "a",
+    you say <code>"b runAfter a"</code>.
+</p>
+<p>
+    For example, <code>compileTest</code> is declared as a <code>runAfter</code> for the task <code>compile</code>.
+    This means that it doesn't make sense to run <code>compileTest</code> unless <code>compile</code> has run first.
+    However, if a user invokes the task <code>compile</code>, they probably don't want to invoke <code>compileTest</code>,
+    so a dependency is exactly what we need here: invoking <code>compileTest</code> will trigger <code>compile</code>
+    but not the other way around.
+</p>
+<p>
+    However, there are times where you want to define a task that will <strong>always</strong> run after a given task.
+    For example, you could have a <code>signJarFile</code> task that should always be invoked if someone builds a jar
+    file. You don't expect users to invoke that target explicitly, but whenever they invoke the <code>assemble</code>
+    target, you want your <code>signJarFile</code> target to be invoked. When you want such a task to always be invoked
+    even if the user didn't explicitly request it, you should use <code>wrapAfter</code>. You are essentially wrapping
+    an existing task with your own task. Note that there is no <code>wrapBefore</code> annotation since <code>runBefore</code>
+    achieves the same functionality.
+</p>
+
 <h3 class="section" indent="1">Dynamic tasks</h3>