Re #6270, further document --haddock-for-hackage

doc/build_command.md

@@ -247,13 +247,13 @@ upload to Hackage.
 
 For each local package, the generated Haddock documentation files are in
 directory `doc\html\<package_version>-docs\`, relative to Stack's dist work
-directory (see `stack path --dist-dir`).
+directory (see [`stack path --dist-dir`](path_command.md)).
 
 If the flag is set:
 
-* the [`--[no-]haddock-hyperlink-source`](#no-haddock-hyperlink-source-flag)
+* the [`--[no-]haddock-hyperlink-source`](#-no-haddock-hyperlink-source-flag)
   flag is ignored and `--haddock-hyperlink-source` is implied; and
-* the [`--[no-]haddock-internal`](#no-haddock-hyperlink-internal-flag) flag is
+* the [`--[no-]haddock-internal`](#-no-haddock-hyperlink-internal-flag) flag is
   ignored and `--no-haddock-internal` is implied.
 
 !!! note
@@ -274,7 +274,7 @@ Default: Enabled
 
 Unset the flag to disable building building hyperlinked source for Haddock.
 
-If the [`--haddock-for-hackage`](#no-haddock-for-haddock-flag) flag is passed,
+If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
 this flag is ignored.
 
 ### `--[no-]haddock-internal` flag
@@ -283,7 +283,7 @@ Default: Disabled
 
 Set the flag to enable building Haddock documentation for internal modules.
 
-If the [`--haddock-for-hackage`](#no-haddock-for-haddock-flag) flag is passed,
+If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
 this flag is ignored.
 
 ### `--[no-]keep-going` flag

doc/yaml_configuration.md

@@ -434,41 +434,61 @@ build:
   # incorrectly formatted.  This could also affect scripts which use Stack.
   haddock: false
   haddock-arguments:
-    haddock-args: [] # Additional arguments passed to haddock, --haddock-arguments
+
+    # Additional arguments passed to haddock. The corresponding command line
+    # option is --haddock-arguments. Example of use:
+    #
     # haddock-args:
     # - "--css=/home/user/my-css"
-  open-haddocks: false # --open
-  haddock-deps: false # if unspecified, defaults to true if haddock is set
-  haddock-for-hackage: false # if specified, implies haddock-internal: false and
-                             # haddock-hyperlink-source: true
-  haddock-internal: false # ignored, if haddock-for-hackage: true
-  haddock-hyperlink-source: true  # ignored, if haddock-for-hackage: true
+    haddock-args: []
+
+  # The corresponding command line flag is --[no-]open.
+  open-haddocks: false
+
+  # If Stack is configured to build Haddock documentation, defaults to true.
+  haddock-deps: false
+
+  # If specified, implies haddock-internal: false and
+  # haddock-hyperlink-source: true. Since Stack UNRELEASED.
+  haddock-for-hackage: false
+
+  # The configuration is ignored, if haddock-for-hackage: true.
+  haddock-internal: false
+
+  # The configuration is ignored, if haddock-for-hackage: true.
+  haddock-hyperlink-source: true
 
   # These are inadvisable to use in your global configuration, as they make the
   # Stack build command line behave quite differently.
   test: false
   test-arguments:
     rerun-tests: true   # Rerun successful tests
-    additional-args: [] # --test-arguments
+
+    # The corresponding command line option is --test-arguments. Example of use:
+    #
     # additional-args:
     # - "--fail-fast"
+    additional-args: []
     coverage: false
     no-run-tests: false
   bench: false
   benchmark-opts:
-    benchmark-arguments: ""
+
+    # Example of use:
+    #
     # benchmark-arguments: "--csv bench.csv"
+    benchmark-arguments: ""
     no-run-benchmarks: false
   force-dirty: false
   reconfigure: false
   cabal-verbose: false
   split-objs: false
 
-  # Since 1.8. Starting with 2.0, the default is true
+  # Since Stack 1.8. Starting with Stack 2.0, the default is true
   interleaved-output: true
-  # Since 2.13.1. Available options are none, count-only, capped and full.
+  # Since Stack 2.13.1. Available options are none, count-only, capped and full.
   progress-bar: capped
-  # Since 1.10.
+  # Since Stack 1.10.
   ddump-dir: ""
 ~~~