document logger module

borg/logger.py

@@ -1,8 +1,47 @@
+"""logging facilities
+
+The way to use this is as follows:
+
+* each module declares its own logger, using:
+
+    from .logger import create_logger
+    logger = create_logger()
+
+* then each module uses logger.info/warning/debug/etc according to the
+  level it believes is appropriate. a first conversion was done, but
+  can be revised later on:
+
+    logger.debug('some intricate details you usually do not care about')
+    logger.info('verbose progress information')
+    logger.warning('some non-error condition that must always be reported')
+    logger.error('a fatal error')
+
+  ... and so on. see the `logging documentation
+  <https://docs.python.org/3/howto/logging.html#when-to-use-logging>`_
+  for more information
+
+* console interaction happens on stderr, that include interactive
+  reporting functions like `help`, `info` and `list`
+
+* ...except ``input()`` is special, because we can't control the
+  stream it is using, unfortunately. we assume that it won't clutter
+  stdout, because interaction would be broken then anyways
+
+* advanced verbosity filters, based on what i described in
+  https://github.com/borgbackup/borg/pull/233#issuecomment-145100222
+  may eventually be implemented
+"""
+
 import inspect
 import logging
 import sys
 
 def setup_logging(args, stream=None):
+    """setup logging module according to the arguments provided
+
+    this sets up a stream handler logger on stderr (by default, if no
+    stream is provided) and verbosity levels.
+    """
     logging.raiseExceptions = False
     l = logging.getLogger('')
     sh = logging.StreamHandler(stream)
@@ -37,4 +76,13 @@ def find_parent_module():
         return __name__
 
 def create_logger(name=None):
+    """create a Logger object with the proper path, which is returned by
+    find_parent_module() by default, or is provided on the commandline
+
+    this is really a shortcut for:
+
+        logger = logging.getLogger(__name__)
+
+    we use it to avoid errors and provide a more standard API.
+    """
     return logging.getLogger(name or find_parent_module())