Clarify documentation of custom request matchers (#479)

* The choice is not what the function *returns*, but what it *does*
  (raising an exception is not returning a value).

* Recommend "assert" more strongly, and additionally recommend an
  error message with the assert.

* Back up that recommendation in the sample code.

docs/advanced.rst

@@ -97,12 +97,12 @@ Create your own method with the following signature
 
     def my_matcher(r1, r2):
 
-Your method receives the two requests and can return :
+Your method receives the two requests and can either:
 
-- Use an ``assert`` statement in the matcher, then we have ``None`` if they match, raise an `AssertionError`` if they don't.
+- Use an ``assert`` statement: return None if they match and raise ``AssertionError`` if not.
-- A boolean, ``True`` if they match, ``False`` if they don't.
+- Return a boolean: ``True`` if they match, ``False`` if not.
 
-Note : You should use an ``assert`` statement in order to have feedback when a matcher is failing.
+Note: in order to have good feedback when a matcher fails, we recommend using an ``assert`` statement with a clear error message.
 
 Finally, register your method with VCR to use your new request matcher.
 
@@ -111,7 +111,8 @@ Finally, register your method with VCR to use your new request matcher.
     import vcr
 
     def jurassic_matcher(r1, r2):
-        assert r1.uri == r2.uri and 'JURASSIC PARK' in r1.body
+        assert r1.uri == r2.uri and 'JURASSIC PARK' in r1.body, \
+            'required string (JURASSIC PARK) not found in request body'
 
     my_vcr = vcr.VCR()
     my_vcr.register_matcher('jurassic', jurassic_matcher)