Clarify docblocks, fixes #142

src/Monolog/Handler/HandlerInterface.php

@@ -25,6 +25,10 @@ interface HandlerInterface
      *
      * This is mostly done for performance reasons, to avoid calling processors for nothing.
      *
+     * Handlers should still check the record levels within handle(), returning false in isHandling()
+     * is no guarantee that handle() will not be called, and isHandling() might not be called
+     * for a given record.
+     *
      * @param array $record
      *
      * @return Boolean
@@ -34,7 +38,12 @@ interface HandlerInterface
     /**
      * Handles a record.
      *
+     * All records may be passed to this method, and the handler should discard
+     * those that it does not want to handle.
+     *
      * The return value of this function controls the bubbling process of the handler stack.
+     * Unless the bubbling is interrupted (by returning true), the Logger class will keep on
+     * calling further handlers in the stack with a given log record.
      *
      * @param  array   $record The record to handle
      * @return Boolean True means that this handler handled the record, and that bubbling is not permitted.