Update user's guide entry on demand analysis and worker/wrapperwip/refactor-demand

The demand signature notation has been undocumented for a long time.
The only source to understand it, apart from reading the `Outputable`
instance, has been an outdated wiki page.

Since the previous commits have reworked the demand lattice, I took
it as an opportunity to also write some documentation about notation.

1 files changed, 10 insertions, 5 deletions

diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst
index 75728ae7d7..836be3a9ea 100644
--- a/docs/users_guide/debugging.rst
+++ b/docs/users_guide/debugging.rst
@@ -334,16 +334,22 @@ subexpression elimination pass.
     its rationale.
 
 .. ghc-flag:: -ddump-stranal
-    :shortdesc: Dump strictness analyser output
+    :shortdesc: Dump demand analysis output
     :type: dynamic
 
-    Dump strictness analyser output
+    Dump demand analysis output.
+
+    See :ghc-flag:`-fstrictness` for the syntax and semantics of demand
+    annotations.
 
 .. ghc-flag:: -ddump-str-signatures
-    :shortdesc: Dump strictness signatures
+    :shortdesc: Dump top-level demand signatures
     :type: dynamic
 
-    Dump strictness signatures
+    Dump top-level demand signatures as produced by demand analysis.
+
+    See :ghc-flag:`-fstrictness` for the syntax and semantics of demand
+    annotations.
 
 .. ghc-flag:: -ddump-cpranal
     :shortdesc: Dump CPR analysis output
@@ -381,7 +387,6 @@ subexpression elimination pass.
 
     Dump output of Core preparation pass
 
-
 STG representation
 ~~~~~~~~~~~~~~~~~~