updated dev docs for actionAllowed changes

master/docs/manual/developer.rst

@@ -383,15 +383,23 @@ form.  These fields are usually generated by the :meth:`auth()` form:
 Once the POST request comes in, it's time to check authorization again.
 This usually looks something like ::
 
-    if not self.getAuthz(req).actionAllowed('myNewTrick', req, someExtraArg):
-        return Redirect(path_to_authfail(req))
+    d = self.getAuthz(req).actionAllowed('myNewTrick', req, someExtraArg)
+    wfd = defer.waitForDeferred(d)
+    yield wfd
+    res = wfd.getResult()
+    if not res:
+        yield Redirect(path_to_authfail(req))
+        return
 
 The ``someExtraArg`` is optional (it's handled with ``*args``, so you can
 have several if you want), and is given to the user's authorization function.
 For example, a build-related action should pass the build status, so that the
 user's authorization function could ensure that devs can only operate on their
 own builds.
 
+Note that ``actionAllowed`` returns a ``Deferred`` instance, so you must wait
+for the ``Deferred`` and yield the ``Redirect`` instead of returning it.
+
 The available actions are listed in :ref:`WebStatus-Configuration-Parameters`.