;lib: Hledger.Utils.Debug: improve module haddock

This commit is contained in:
Simon Michael 2020-12-09 13:23:30 -08:00
parent e9b84ca17c
commit 51e3e9cbfa

View File

@ -1,31 +1,23 @@
{-# LANGUAGE FlexibleContexts, TypeFamilies #-} {-# LANGUAGE FlexibleContexts, TypeFamilies #-}
{- | Debugging helpers. {- |
You can enable increasingly verbose debug output by adding --debug [1-9] Helpers for debug output and pretty-printing
to a hledger command line. --debug with no argument means --debug 1. (using pretty-simple, with which there may be some overlap).
This is implemented by calling dbgN or similar helpers, defined below.
These calls can be found throughout hledger code; they have been added
organically where it seemed likely they would be needed again.
The choice of debug level has not been very systematic.
202006 Here's a start at some guidelines, not yet applied project-wide:
Debug level: What to show: @dbg0@-@dbg9@ will pretty-print values to stderr
------------ --------------------------------------------------------- if the program was run with a sufficiently high @--debug=N@ argument.
0 normal command output only (no warnings, eg) (@--debug@ with no argument means @--debug=1@; @dbg0@ always prints).
1 (--debug) useful warnings, most common troubleshooting info, eg valuation
2 common troubleshooting info, more detail
3 report options selection
4 report generation
5 report generation, more detail
6 input file reading
7 input file reading, more detail
8 command line parsing
9 any other rarely needed / more in-depth info
Tip: when debugging with GHCI, the first run after loading Debug.hs sets the The @debugLevel@ global is set once at startup using unsafePerformIO.
debug level. If you need to change it, you must touch Debug.hs, :reload in GHCI, In GHCI, this happens only on the first run of :main, so if you want
then run the command with a new --debug value. Or, often it's more convenient to change the debug level without restarting GHCI,
to add a temporary dbg0 and :reload (dbg0 always prints). save a dummy change in Debug.hs and do a :reload.
(Sometimes it's more convenient to temporarily add dbg0's and :reload.)
@traceParse@ and @dbgparse@ print current status of hledger's parsers
(similar to megaparsec's dbg, which was added later).
This module also exports Debug.Trace.
-} -}