Merge branch '1.x', clean up close/reset for 2.0, refs #997

src/Monolog/Handler/HandlerInterface.php

@@ -59,10 +59,18 @@ interface HandlerInterface
     /**
      * Closes the handler.
      *
-     * This will be called automatically when the object is destroyed if you extend Monolog\Handler\Handler
+     * Ends a log cycle and frees all resources used by the handler.
+     *
+     * Closing a Handler means flushing all buffers and freeing any open resources/handles.
      *
      * Implementations have to be idempotent (i.e. it should be possible to call close several times without breakage)
      * and ideally handlers should be able to reopen themselves on handle() after they have been closed.
+     *
+     * This is useful at the end of a request and will be called automatically when the object
+     * is destroyed if you extend Monolog\Handler\Handler.
+     *
+     * If you are thinking of calling this method yourself, most likely you should be
+     * calling ResettableInterface::reset instead. Have a look.
      */
     public function close(): void;
 }