From e4ac8bd15d47a236d8800d85a3c46ce013245c0e Mon Sep 17 00:00:00 2001
From: Scott Gasch <scott@gasch.org>
Date: Fri, 14 Oct 2022 14:58:10 -0700
Subject: [PATCH] Improve documentation in bootstrap.py.

---
 src/pyutils/bootstrap.py | 47 +++++++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/src/pyutils/bootstrap.py b/src/pyutils/bootstrap.py
index 5a59615..8dc4a0c 100644
--- a/src/pyutils/bootstrap.py
+++ b/src/pyutils/bootstrap.py
@@ -2,21 +2,38 @@
 
 # © Copyright 2021-2022, Scott Gasch
 
-"""This is a module for wrapping around python programs and doing some
-minor setup and tear down work for them.  With it, you will get:
-
-* The ability to break into pdb on unhandled exceptions,
-* automatic support for :file:`config.py` (argument parsing)
-* automatic logging support for :file:`logging.py`,
-* the ability to enable code profiling,
-* the ability to enable module import auditing,
-* optional memory profiling for your program,
-* ability to set random seed via commandline,
-* automatic program timing and reporting,
-* more verbose error handling and reporting,
-
-Most of these are enabled and/or configured via commandline flags
-(see below).
+"""
+If you decorate your main method (i.e. program entry point) like this::
+
+    @bootstrap.initialize
+    def main():
+        whatever
+
+...you will get:
+
+    * automatic support for :py:mod:`pyutils.config` (argument parsing, see
+      that module for details),
+    * The ability to break into pdb on unhandled exceptions (which is
+      enabled/disabled via the commandline flag `--debug_unhandled_exceptions`),
+    * automatic logging support from :py:mod:`pyutils.logging` controllable
+      via several commandline flags,
+    * the ability to optionally enable whole-program code profiling and reporting
+      when you run your code using commandline flag `--run_profiler`,
+    * the ability to optionally enable import auditing via the commandline flag
+      `--audit_import_events`.  This logs a message whenever a module is imported
+      *after* the bootstrap module itself is loaded.  Note that other modules may
+      already be loaded when bootstrap is loaded and these imports will not be
+      logged.  If you're trying to debug import events or dependency problems,
+      I suggest putting bootstrap very early in your import list and using this
+      flag.
+    * optional memory profiling for your program set via the commandline flag
+      `--trace_memory`.  This provides a report of python memory utilization
+      at program termination time.
+    * the ability to set the global random seed via commandline flag for
+      reproducable runs (as long as subsequent code doesn't reset the seed)
+      using the `--set_random_seed` flag,
+    * automatic program timing and reporting logged to the INFO log,
+    * more verbose error handling and reporting.
 
 """
 
-- 
2.45.2