1 files changed, 39 insertions, 7 deletions
diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst
index a2fbf99..cec8e30 100644
--- a/docs/source/buildfile.rst
+++ b/docs/source/buildfile.rst
@@ -63,7 +63,7 @@ Next, we will look at a new target::
 This is a standard definition of a Python function with a decorator.
 
 First, the ``target`` decorator marks the function definition as a target (to
-be used by the ``list-targets`` command, see :ref:`specialTargets`). Next, we
+be used by the ``list-targets`` command, see :ref:`otherCommands`). Next, we
 define the function; this function name *is* the name of the target. That is,
 the name given to the function will be the name given to the command to invoke
 this target.  Further, we have the docstring; (this is also used by the
@@ -77,10 +77,32 @@ Return Values
 =============
 
 The targets you define can return an error code (or '0' for success) however
-you see fit. Doing this will give you a status message at the end of the
-invocation of Xnt that will inform you if the target ran successfully or not
-given your criteria (or will just say it succeeded if you don't specify a
-return value at all). For example::
+you see fit. Xnt will emit 'Failure' if the status code is *not* zero and will
+otherwise remain silent if the code is zero. Further, the status code returned
+by your target will be returned as the exit code of Xnt when finished
+executing.
+
+*Notice*, this allows Xnt to fail fast when attempting to execute multiple
+targets. That is, if you specify more than one target, Xnt will stop at the
+first failure.
+
+If you don't define a return value for a target, Xnt will assume success and
+return '0'.
+
+Examples
+--------
+
+Not defining the return value::
+
+    @target
+    def foo():
+        pass
+
+Will result in (no success message; other output may be shown)::
+
+    ...
+
+Returning success (no success message; other output may be shown)::
 
     @target
     def foo():
@@ -89,9 +111,19 @@ return value at all). For example::
 Will result in::
 
     ...
-    Success
 
-Most tasks have been updated to return error codes as well to that you can
+Returning failure (not 0)::
+
+    @target
+    def foo():
+        return 1
+
+Will result in::
+
+    ...
+    Failure
+
+Most tasks have been updated to return error codes as well so that you can
 return what it returns. If you find any tasks that can be updated to behave
 this way, please create an issue for it.