Index: twisted/trial/test/test_asyncassertions.py
===================================================================
--- twisted/trial/test/test_asyncassertions.py	(revision 36342)
+++ twisted/trial/test/test_asyncassertions.py	(working copy)
@@ -17,14 +17,23 @@
 class TestAsynchronousAssertions(unittest.TestCase):
     """
     Tests for L{TestCase}'s asynchronous extensions to L{SynchronousTestCase}.
-    That is, assertFailure.
+    That is, L{TestCase.assertFailure}.
     """
     def test_assertFailure(self):
+        """
+        Test that a L{ZeroDivisionError} is raised when we try to run 1/0 in a
+        deferred lambda function, and that assertFailure catches it.
+        """
         d = defer.maybeDeferred(lambda: 1/0)
         return self.assertFailure(d, ZeroDivisionError)
 
 
     def test_assertFailure_wrongException(self):
+        """
+        Test that assertFailure, when called on a function that raises a
+        L{ZeroDivisionError}, will fail the deferred function if it instead
+        raises an L{OverflowError}.
+        """
         d = defer.maybeDeferred(lambda: 1/0)
         self.assertFailure(d, OverflowError)
         d.addCallbacks(lambda x: self.fail('Should have failed'),
@@ -33,6 +42,10 @@
 
 
     def test_assertFailure_noException(self):
+        """
+        Test that assertFailure will fail the deferred function if there is no
+        exception raised, and a L{ZeroDivisionError} was expected.
+        """
         d = defer.succeed(None)
         self.assertFailure(d, ZeroDivisionError)
         d.addCallbacks(lambda x: self.fail('Should have failed'),
@@ -44,6 +57,8 @@
         """
         In the case of assertFailure failing, check that we get lots of
         information about the exception that was raised.
+
+        See L{_checkInfo} for more information about the checks we run.
         """
         try:
             1/0
@@ -56,6 +71,13 @@
 
 
     def _checkInfo(self, assertionFailure, f):
+        """
+        Given an assertion failure and the failure that caused it, check that
+        the information in the L{failure} objects match up.
+
+        Specifically, we check for the error message and the brief traceback,
+        see L{failure.getErrorMessage} and L{failure.getBriefTraceback}.
+        """
         assert assertionFailure.check(self.failureException)
         output = assertionFailure.getErrorMessage()
         self.assertIn(f.getErrorMessage(), output)
@@ -64,7 +86,13 @@
 
     def test_assertFailure_masked(self):
         """
-        A single wrong assertFailure should fail the whole test.
+        Run an actual L{unittest.TestCase} with some calls to assertFailure,
+        and make sure that the test case fails when the assertFailure is sure
+        to fail.
+
+        Specifically, we defer a lambda: 1/0, and assert that it will fail with
+        an L{OverflowError}, when clearly it will fail with a
+        L{ZeroDivisionError} instead, so that test case should fail.
         """
         class ExampleFailure(Exception):
             pass