Clean up log module documentation

erynrl/log.py

@@ -1,13 +1,14 @@
 # Eryn Wells <eryn@erynwells.me>
 
 '''
-Initializes and sets up
+Initializes and sets up logging for the game.
 '''
 
 import json
 import logging
 import logging.config
 import os.path
+from typing import Iterator, Optional
 
 # These are re-imports so clients of this module don't have to also import logging
 # pylint: disable=unused-import
@@ -24,20 +25,38 @@ ACTIONS = logging.getLogger(_log_name('actions'))
 ACTIONS_TREE = logging.getLogger(_log_name('actions', 'tree'))
 ENGINE = logging.getLogger(_log_name('engine'))
 EVENTS = logging.getLogger(_log_name('events'))
-MAP = logging.getLogger(_log_name('map'))
 UI = logging.getLogger(_log_name('ui'))
 
+MAP = logging.getLogger(_log_name('map'))
+MAP_CELL_ATOM = logging.getLogger(_log_name('map', 'cellular'))
 
-def walk_up_directories_of_path(path):
+
-    '''Walk up a path, yielding each directory, until the root of the filesystem is found'''
+def walk_up_directories_of_path(path: str) -> Iterator[str]:
+    '''
+    Walk up a path, yielding each directory, until the root of the filesystem is
+    found.
+
+    ### Parameters
+    `path`: `str`
+        The starting path
+
+    ### Returns
+    Yields each ancestor directory until the root directory of the filesystem is
+    reached.
+    '''
     while path and path != '/':
         if os.path.isdir(path):
             yield path
         path = os.path.dirname(path)
 
 
-def find_logging_config():
+def find_logging_config() -> Optional[str]:
-    '''Walk up the filesystem from this script to find a logging_config.json'''
+    '''
+    Walk up the filesystem from this script to find a logging_config.json
+
+    ### Returns
+    The path to a logging configuration file, or `None` if no such file was found
+    '''
     for parent_dir in walk_up_directories_of_path(__file__):
         possible_logging_config_file = os.path.join(parent_dir, 'logging_config.json')
         if os.path.isfile(possible_logging_config_file):
@@ -49,23 +68,26 @@ def find_logging_config():
     return possible_logging_config_file
 
 
-def init(config_file=None):
+def init(config_file: Optional[str] = None):
     '''
     Set up the logging system by (preferrably) reading a logging configuration file.
 
-    Parameters
+    ### Parameters
-    ----------
+    `config_file`: Optional[str]
-    config_file : str
         Path to a file containing a Python logging configuration in JSON
     '''
     logging_config_path = config_file if config_file else find_logging_config()
 
-    if os.path.isfile(logging_config_path):
+    if logging_config_path and os.path.isfile(logging_config_path):
+        ROOT.info('Found logging configuration at %s', logging_config_path)
         with open(logging_config_path, encoding='utf-8') as logging_config_file:
             logging_config = json.load(logging_config_file)
             logging.config.dictConfig(logging_config)
-        ROOT.info('Found logging configuration at %s', logging_config_path)
     else:
+        ROOT.info(
+            "Couldn't find logging configuration at %s; using default configuration",
+            logging_config_path)
+
         root_logger = logging.getLogger('')
         root_logger.setLevel(logging.DEBUG)