From ed0248ce3f71335f55a4abeb0056f2c7872e47b0 Mon Sep 17 00:00:00 2001
From: Cedric Beust <cedric@beust.com>
Date: Tue, 19 Apr 2016 05:04:20 -0800
Subject: [PATCH] Clarify task dependencies.

---
 plug-in-development/index.html | 61 +++++++++++++++-------------------
 1 file changed, 26 insertions(+), 35 deletions(-)

diff --git a/plug-in-development/index.html b/plug-in-development/index.html
index 094fe2b..13d014d 100644
--- a/plug-in-development/index.html
+++ b/plug-in-development/index.html
@@ -470,7 +470,7 @@ The <code>@Task</code> annotation accepts the following attributes:
     If your task cannot run until another task has run, you need to declare a dependency. Dependencies cause
     additional tasks than those requested to be executed. For example, <code>"assemble"</code> depends on <code>"compile"</code>, which means that whenever you invoke <code>"assemble"</code>, <code>"compile"</code>
     will be automatically run first. This is a dependency and it is controlled by <code>"dependsOn"</code> and
-    <code>"reverseDependsOn"</code>.
+    <code>"reverseDependsOn"</code>. You can see <code>"reverseDependsOn"</code> as a way to insert your task before an existing task.
 </p>
 <p>
     Orderings, controlled by <code>"runBefore"</code> and <code>"runAfter"</code> merely specify an ordering
@@ -479,58 +479,49 @@ The <code>@Task</code> annotation accepts the following attributes:
     by the user).
 </p>
 <p>
-    The reverse direction attributes <code>"reverseDependsOn"</code> and <code>"runAfter"</code> are useful
-    when you want to declare a dependency/ordering on a task that you do not control, and that you can therefore
-    not modify.
-</p>
-</p>
-<p>
-For example, <code>compileTest</code> is declared as <code>"dependsOn"</code> 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>
-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>"reverseDependsOn"</code>.
-</p>
-<p>
-Here are a few different scenarios to illustrate how the three attributes work for the task <code>exampleTask</code>:
+Here are a few different scenarios to illustrate how the three attributes work for the task <code>example</code>:
 </p>
 <p align="center">
 <strong>Result of the command <code>./kobaltw --dryRun compile</code></strong>
 </p>
 <table width="100%" class="table table-bordered table-condensed">
     <thead>
-        <td align="center">Configuration for <code>exampleTask</code></td>
+        <td align="center">Configuration for <code>example</code></td>
         <td align="center">Result</td>
+        <td align="center">Note</td>
     </thead>
     <tr>
-        <td align="center">runBefore = "compile"</td>
+        <td align="center">dependsOn = "compile"</td>
         <td>
-<pre class="brush:plain">kobalt-line-count:clean
-kobalt-line-count:exampleTask
-kobalt-line-count:compile</pre>
+<pre class="brush:plain">clean
+compile
+example</pre>
         </td>
-    </tr>
-    <tr>
-        <td align="center">runAfter = "compile"</td>
         <td>
-<pre class="brush:plain">kobalt-line-count:clean
-kobalt-line-count:compile</pre>
+            Make the <code>"example"</code> task depend on <code>"compile"</code>.
         </td>
     </tr>
     <tr>
         <td align="center">reverseDependsOn = "compile"</td>
         <td>
-<pre class="brush:plain">kobalt-line-count:clean
-kobalt-line-count:compile
-kobalt-line-count:exampleTask</pre>
+<pre class="brush:plain">clean
+example
+compile</pre>
         </td>
+        <td>
+            Insert the <code>"example"</code> task before <code>"compile"</code>.
+        </td>
+    </tr>
+    <tr>
+        <td align="center">runAfter = "compile"</td>
+        <td>
+<pre class="brush:plain">clean
+compile</pre>
+        </td>
+        <td>
+            Make <code>"example"</code> run after <code>"compile"</code> but only if it's invoked explicitly.
+        </td>
+
     </tr>
 </table>
 <h3 class="section" indent="1">Dynamic tasks</h3>