Document the --debug options.

2 files changed, 21 insertions, 0 deletions

diff --git a/doc/cmd.rst b/doc/cmd.rst
index 81a8fbe6..3572fff4 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -138,6 +138,24 @@ could affect the measurement process.  The possible warnings include:
   This could be because you asked to measure only modules that never ran,
   or for other reasons.
 
+.. _cmd_run_debug:
+
+The ``--debug`` option instructs coverage to log internal details of its
+operation, to help with diagnosing problems.  It takes a comma-separated list
+of options, each indicating a facet of operation to log to stderr:
+
+* ``trace``: print every decision about whether to trace a file or not. For
+  files not being traced, the reason is also given.
+
+* ``config``: before starting, dump all the :ref:`configuration <config>`
+  values.
+
+* ``sys``: before starting, dump all the system and environment information,
+  as with :ref:`coverage debug sys <cmd_debug>`.
+  
+* ``dataio``: log when reading or writing any data file.
+  
+* ``pid``: annotate all debug output with the process id.
 
 
 .. _cmd_datafile:
diff --git a/doc/config.rst b/doc/config.rst
index c32d401e..7ff82021 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -93,6 +93,9 @@ standard library.
 ``data_file`` (string, default ".coverage"): the name of the data file to use
 for storing or reporting coverage.
 
+``debug`` (multi-string): a list of debug options.  See :ref:`the run
+--debug option <cmd_run_debug>` for details.
+
 ``include`` (multi-string): a list of filename patterns, the files to include
 in measurement or reporting.  See :ref:`source` for details.