Fix breadcrumb log handling docs.

The documentation stated that handlers should return `False` to skip log
recording while it is in fact the opposite any value that evaluates to
true will skip recording.

Additionally:
1. Added note about the useful `allow_level` param to `ignore_logger`.
2. Added info about one-callback per logger name limit.
3. Explained that callbacks need to be registered for initial logger
names – that parent logger names do not influence breadcrumb recording.
4. Removed confusing note about `ignore_logger` from method __doc__.
`register_special_log_handler` should be used for special handling of
framework logging.

2 files changed, 22 insertions, 16 deletions

diff --git a/docs/breadcrumbs.rst b/docs/breadcrumbs.rst
index 51348cf..642005d 100644
--- a/docs/breadcrumbs.rst
+++ b/docs/breadcrumbs.rst
@@ -48,7 +48,7 @@ the logging system or to disable loggers entirely.  For this you can use
 the :py:func:`~raven.breadcrumbs.ignore_logger` and
 :py:func:`~raven.breadcrumbs.register_special_log_handler` functions:
 
-.. py:function:: raven.breadcrumbs.ignore_logger(name_or_logger)
+.. py:function:: raven.breadcrumbs.ignore_logger(name_or_logger, allow_level=None)
 
     If called with the name of a logger, this will ignore all messages
     that come from that logger.  For instance if you have a very spammy
@@ -56,14 +56,17 @@ the :py:func:`~raven.breadcrumbs.ignore_logger` and
 
 .. py:function:: raven.breadcrumbs.register_special_log_handler(name_or_logger, callback)
 
-    This registers a callback as a handler for a given logger.  This can
-    be used to ignore or convert log messages.  The callback is invoked
-    with the following arguments: ``logger, level, msg, args, kwargs``.
-    If the callback returns `False` nothing is logged, if it returns
-    `True` the default handling kicks in.
+    Registers a callback for log handling. The callback is invoked
+    with given arguments: `logger`, `level`, `msg`, `args` and `kwargs`
+    which are the values passed to the logging system. If the callback
+    returns true value the default handling is disabled. Only one callback
+    can be registered per one logger name. Logger tree is not traversed
+    so calling this method with `spammy_module` argument will not silence
+    messages from `spammy_module.child`.
 
     Typically it makes sense to invoke
-    :py:func:`~raven.breadcrumbs.record` from it.
+    :py:func:`~raven.breadcrumbs.record` from it unless you want to silence
+    a message based on its attributes other than `level`.
 
 .. py:function:: raven.breadcrumbs.register_logging_handler(callback)
 
diff --git a/raven/breadcrumbs.py b/raven/breadcrumbs.py
index 3980b88..85b1b8c 100644
--- a/raven/breadcrumbs.py
+++ b/raven/breadcrumbs.py
@@ -238,9 +238,7 @@ def install_logging_hook():
 
 
 def ignore_logger(name_or_logger, allow_level=None):
-    """Ignores a logger for the regular breadcrumb code.  This is useful
-    for framework integration code where some log messages should be
-    specially handled.
+    """Ignores a logger during breadcrumb recording.
     """
     def handler(logger, level, msg, args, kwargs):
         if allow_level is not None and \
@@ -251,10 +249,13 @@ def ignore_logger(name_or_logger, allow_level=None):
 
 
 def register_special_log_handler(name_or_logger, callback):
-    """Registers a callback for log handling.  The callback is invoked
-    with give arguments: `logger`, `level`, `msg`, `args` and `kwargs`
-    which are the values passed to the logging system.  If the callback
-    returns `True` the default handling is disabled.
+    """Registers a callback for log handling. The callback is invoked
+    with given arguments: `logger`, `level`, `msg`, `args` and `kwargs`
+    which are the values passed to the logging system. If the callback
+    returns true value the default handling is disabled. Only one callback
+    can be registered per one logger name. Logger tree is not traversed
+    so calling this method with `spammy_module` argument will not silence
+    messages from `spammy_module.child`.
     """
     if isinstance(name_or_logger, string_types):
         name = name_or_logger
@@ -265,10 +266,12 @@ def register_special_log_handler(name_or_logger, callback):
 
 def register_logging_handler(callback):
     """Registers a callback for log handling.  The callback is invoked
-    with give arguments: `logger`, `level`, `msg`, `args` and `kwargs`
+    with given arguments: `logger`, `level`, `msg`, `args` and `kwargs`
     which are the values passed to the logging system.  If the callback
-    returns `True` the default handling is disabled.
+    returns true value the default handling is disabled. Registering
+    multiple handlers is allowed.
     """
+
     special_logging_handlers.append(callback)