abandoned pull request revived to comply with comments in review

doc/for-test-authors.rst

@@ -292,8 +292,7 @@ Which is roughly equivalent to::
 ------------------------
 
 In addition to ``self.assertThat``, testtools also provides the ``assert_that``
-function in ``testtools.assertions`` (which is what ``self.assertThat`` backs
-on to internally).  This behaves as the method version does::
+function in ``testtools.assertions`` This behaves like the method version does::
 
     class TestSquare(TestCase):
 

testtools/assertions.py

@@ -7,6 +7,10 @@ from testtools.matchers import (
 def assert_that(matchee, matcher, message='', verbose=False):
     """Assert that matchee is matched by matcher.
 
+    This should only be used when you need to use a function based
+    matcher, assertThat in Testtools.Testcase is prefered and has more
+    features
+
     :param matchee: An object to match with matcher.
     :param matcher: An object meeting the testtools.Matcher protocol.
     :raises MismatchError: When matcher does not match thing.

testtools/tests/test_assert_that.py

@@ -20,9 +20,7 @@ from testtools.matchers import (
 
 
 class AssertThatTests(object):
-    """
-    A mixin containing shared tests for assertThat and assert_that.
-    """
+    """A mixin containing shared tests for assertThat and assert_that."""
 
     def assert_that_callable(self, *args, **kwargs):
         raise NotImplementedError