diff --git a/Shake.hs b/Shake.hs
index 20ab5b35c..735a7dc57 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -612,9 +612,9 @@ main = do
       --   need commandmdsnew
       --   when commit $ commitIfChanged ";doc: update command flag docs" commandmds
 
-      -- hledger/Hledger/Cli/Commands/CMD.md.new: a phony target that updates the flags doc
-      -- within hledger/Hledger/Cli/Commands/CMD.md. Runs "stack run -- hledger CMD -h" to get the latest.
-      -- If that fails, a warning is printed and it carries on, keeping the old flags doc.
+      -- hledger/Hledger/Cli/Commands/CMD.md.new: a phony target that updates the options help
+      -- within hledger/Hledger/Cli/Commands/CMD.md with the output of "stack run -- hledger CMD --help".
+      -- If that fails, a warning is printed and it carries on, keeping the old options help.
       -- NB this needs the hledger build to be up to date, see cmddocs.
       phonys $ \out ->
         if not $ "hledger/Hledger/Cli/Commands/" `isPrefixOf` out && ".md.new" `isSuffixOf` out
diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs
index 5e27ae8f1..057264c07 100644
--- a/hledger/Hledger/Cli/CliOptions.hs
+++ b/hledger/Hledger/Cli/CliOptions.hs
@@ -142,8 +142,8 @@ prognameandversion =
   progname
   packageversion
 
--- common cmdargs flags
--- keep synced with flag docs in doc/common.m4
+-- Common options.
+-- keep synced: the docs macro in doc/common.m4
 
 -- | Common input-related flags: --file, --rules, --conf, --alias...
 inputflags :: [Flag RawOpts]
@@ -184,7 +184,7 @@ inputflags = [
 reportflags :: [Flag RawOpts]
 reportflags = [
 
-  -- report period & interval
+  -- report period, interval, dates
   flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/transactions on/after this date"
  ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/transactions before this date (with a report interval, will be adjusted to following subperiod end)"
  ,flagNone ["daily","D"]     (setboolopt "daily")     "multiperiod report with 1 day interval"
@@ -196,13 +196,13 @@ reportflags = [
  ,flagReq  ["today"]         (\s opts -> Right $ setopt "today" s opts) "DATE" "override today's date (affects relative dates)"
  ,flagNone ["date2"]         (setboolopt "date2") "match/use secondary dates instead (deprecated)"  -- see also hiddenflags
 
-  -- status/realness/depth/zero filters
+  -- status/realness/zero/depth filters
  ,flagNone ["unmarked","U"]  (setboolopt "unmarked") "include only unmarked postings/transactions"
  ,flagNone ["pending","P"]   (setboolopt "pending")  "include only pending postings/transactions"
  ,flagNone ["cleared","C"]   (setboolopt "cleared")  "include only cleared postings/transactions\n(-U/-P/-C can be combined)"
  ,flagNone ["real","R"]      (setboolopt "real")     "include only non-virtual postings"
- ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "DEPTHEXP" "if a number (or -NUM): show only top NUM levels of accounts. If REGEXP=NUM, only apply limiting to accounts matching the regular expression."
  ,flagNone ["empty","E"]     (setboolopt "empty") "Show zero items, which are normally hidden.\nIn hledger-ui & hledger-web, do the opposite."
+ ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "DEPTHEXP" "if a number (or -NUM): show only top NUM levels of accounts. If REGEXP=NUM, only apply limiting to accounts matching the regular expression."
 
   -- valuation
  ,flagNone ["B","cost"]      (setboolopt "B") "show amounts converted to their cost/sale amount"
@@ -224,6 +224,8 @@ reportflags = [
       ,"'now':      value today"
       ,"YYYY-MM-DD: value on given date"
       ])
+
+  -- display
  ,flagReq ["commodity-style", "c"] (\s opts -> Right $ setopt "commodity-style" s opts) "S"
     "Override a commodity's display style.\nEg: -c '$1000.' or -c '1.000,00 EUR'"
  ,flagOpt "yes" ["pretty"] (\s opts -> Right $ setopt "pretty" s opts) "YN"
@@ -444,13 +446,13 @@ hledgerCommandMode helpstr unnamedflaggroup namedflaggroups hiddenflaggroup args
         ,modeArgs        = argsdescr
         }
 
--- | Parse a command's help text file (@Somecommand.txt@).
--- This is generated by @Shake cmdhelp@ from the command's doc source (@Somecommand.md@).
+-- | Parse a command's embedded help text (@Somecommand.txt@).
+-- That text is generated by @Shake cmdhelp@ from the command's doc source (@Somecommand.md@).
 -- @Somecommand.md@ should be formatted as follows:
 --
--- - First line: main command name, as a markdown heading.
+-- - First line: the command name, as a markdown heading.
 --
--- - Optional parenthesised third line: an official abbreviation of the command name.
+-- - Optional third line: the command's official abbreviated name, parenthesised.
 --
 -- - From third or fifth line to a @```flags@ line: the command help preamble.
 --   Usually one sentence or paragraph; any blank lines will not be rendered.