Clarify logging and on_error documentation

Change the description of on_error to reflect that exceptions are logged
and not output by default. Add a note about not configuring logging
causing exceptions to be silently ignored in handlers in the API. And
add some more explanations and a simpler configuration example to the
logging description.

2 files changed, 47 insertions, 17 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 2d4bd69b..6da78bb5 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -17,9 +17,18 @@ Client
 Event Reference
 ~~~~~~~~~~~~~~~~
 
-This page outlines the different types of events listened to by :meth:`Client.event`.
-All events are 'sandboxed', in that if an exception is thrown while the event is called then it is caught and propagated to :func:`on_error`.
+This page outlines the different types of events listened to by
+:meth:`Client.event`.
 
+If an event handler raises an exception, :func:`on_error` will be called
+to handle it, which defaults to log a traceback and ignore the exception.
+
+.. note::
+
+    If the Python logging module is not configured, the logs will not be
+    output anywhere. Meaning that exceptions in handlers will be
+    silently ignored. See :ref:`logging` for more information on how to
+    set up and use the logging module with discord.py.
 
 .. function:: on_ready()
 
@@ -32,21 +41,20 @@ All events are 'sandboxed', in that if an exception is thrown while the event is
 
 .. function:: on_error(event, \*args, \*\*kwargs)
 
-    Usually when an event throws an uncaught exception, a traceback is
-    printed to stderr and the exception is ignored.  If you want to
-    change this behaviour and handle the uncaught exception for whatever
-    reason, this event can be overridden.  The default behaviour for
-    on_error is printing a traceback and then ignoring the exception,
-    but defining an on_error handler will supress this behaviour.
+    Usually when an event raises an uncaught exception, a traceback is
+    logged and the exception is ignored. If you want to change this
+    behaviour and handle the exception for whatever reason yourself,
+    this event can be overridden. Which, when done, will supress the
+    default logging done.
+
+    The information of the exception rasied and the exception itself can
+    be retreived with a standard call to ``sys.exc_info()``.
 
     If you want exception to propogate out of the :class:`Client` class
     you can define an ``on_error`` handler consisting of a single empty
     ``raise`` statement.  Exceptions raised by ``on_error`` will not be
     handled in any way by :class:`Client`.
 
-    The information of the exception rasied can be retreived with a
-    standard call to ``sys.exc_info()``.
-
     :param event: The name of the event that raised the exception.
     :param args: The positional arguments for the event that raised the
         exception.
diff --git a/docs/logging.rst b/docs/logging.rst
index 86a31ae7..80b15273 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -1,11 +1,27 @@
 Setting Up Logging
 ===================
 
-Newer version of *discord.py* have the capability of logging certain events via the `logging`_ python module.
+*discord.py* logs errors, exceptions, and debug information via the
+`logging`_ python module. It is strongly recommended that the logging
+module is configured, as no errors or warnings will be output at all if
+it is not set up. Configuration of the ``logging`` module can be as
+simple as::
 
-This is helpful if you want to see certain issues in *discord.py* or want to listen to events yourself.
+    import logging
+
+    logging.basicConfig(level=logging.INFO)
+
+Placed at the start of the application. This will output the logs from
+discord as well as other libraries that uses the ``logging`` module
+directly to the console.
 
-Setting up logging is fairly simple: ::
+The optinal ``level`` argument specifies what level of events to log
+out and can any of ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and
+``DEBUG`` and if not specified defaults to ``WARNING``.
+
+More advance setups are possible with the ``logging`` module.  To for
+example write the logs to a file called ``discord.log`` instead of
+outputting them to to the console the following snippet can be used::
 
     import discord
     import logging
@@ -16,9 +32,15 @@ Setting up logging is fairly simple: ::
     handler.setFormatter(logging.Formatter('%(asctime)s:%(levelname)s:%(name)s: %(message)s'))
     logger.addHandler(handler)
 
-This would create a logger that writes to a file called ``discord.log``. This is recommended as there are a lot of events
-logged at a time and it would clog out the stdout of your program.
+This is recommended, especially at verbose levels such as ``INFO``,
+and ``DEBUG`` as there are a lot of events logged and it would clog the
+stdout of your program.
+
+.. note::
+
+    The logging facilities were added in version 0.6 of discord.py.
 
-For more information, check the documentation and tutorial of the `logging`_ module.
+For more information, check the documentation and tutorial of the
+`logging`_ module.
 
 .. _logging: https://docs.python.org/2/library/logging.html