Style & documentation tweaks from review

doc/conf.py

@@ -197,6 +197,7 @@ latex_documents = [
 #latex_use_modindex = True
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/2', None),
+    'py2': ('https://docs.python.org/2', None),
+    'py3': ('https://docs.python.org/3', None),
     'twisted': ('https://twistedmatrix.com/documents/current/api/', None),
 }

testtools/_deferred.py

@@ -11,8 +11,8 @@ class DeferredNotFired(Exception):
     """Raised when we extract a result from a Deferred that's not fired yet."""
 
     def __init__(self, deferred):
-        super(DeferredNotFired, self).__init__(
-            "%r has not fired yet." % (deferred,))
+        msg = "%r has not fired yet." % (deferred,)
+        super(DeferredNotFired, self).__init__(msg)
 
 
 def extract_result(deferred):
@@ -24,8 +24,10 @@ def extract_result(deferred):
     case, you can use this function to convert the result back into the usual
     form for a synchronous API, i.e. the result itself or a raised exception.
 
-    It would be very bad form to use this as some way of checking if a
-    Deferred has fired.
+    As a rule, this function should not be used when operating with
+    asynchronous Deferreds (i.e. for normal use of Deferreds in application
+    code). In those cases, it is better to add callbacks and errbacks as
+    needed.
     """
     failures = []
     successes = []
@@ -42,10 +44,10 @@ class ImpossibleDeferredError(Exception):
     """Raised if a Deferred somehow triggers both a success and a failure."""
 
     def __init__(self, deferred, successes, failures):
+        msg = ('Impossible condition on %r, got both success (%r) and '
+               'failure (%r)')
         super(ImpossibleDeferredError, self).__init__(
-            'Impossible condition on {}, got both success ({}) and '
-            'failure ({})'.format(deferred, successes, failures)
-        )
+            msg % (deferred, successes, failures))
 
 
 def on_deferred_result(deferred, on_success, on_failure, on_no_result):

testtools/_deferredmatchers.py

@@ -6,12 +6,13 @@ A "synchronous" Deferred is one that does not need the reactor or any other
 asynchronous process in order to fire.
 
 Normal application code can't know when a Deferred is going to fire, because
-that is generally left up to the reactor. Well-written unit tests provide fake
-reactors, or don't use the reactor at all, so that Deferreds fire
+that is generally left up to the reactor. Unit tests can (and should!) provide
+fake reactors, or don't use the reactor at all, so that Deferreds fire
 synchronously.
 
 These matchers allow you to make assertions about when and how Deferreds fire,
 and about what values they fire with.
+
 """
 
 # TODO: None of these are published yet. Decide where & how to make them
@@ -160,9 +161,6 @@ class _Failed(object):
 
 
 # XXX: The Twisted name is failureResultOf. Do we want to use that name?
-#
-# XXX: failureResultOf also takes an *args of expected exception types. Do we
-# want to provide that?
 def failed(matcher):
     """Match a Deferred that has failed.