cmd/compile: better formatting for ssa phases options doc

Change the help doc of

  go tool compile -d=ssa/help

from this:

  compile: GcFlag -d=ssa/<phase>/<flag>[=<value>|<function_name>]
  <phase> is one of:
  check, all, build, intrinsics, early_phielim, early_copyelim
  early_deadcode, short_circuit, decompose_user, opt, zero_arg_cse
  opt_deadcode, generic_cse, phiopt, nilcheckelim, prove, loopbce
  decompose_builtin, softfloat, late_opt, generic_deadcode, check_bce
  fuse, dse, writebarrier, insert_resched_checks, tighten, lower
  lowered_cse, elim_unread_autos, lowered_deadcode, checkLower
  late_phielim, late_copyelim, phi_tighten, late_deadcode, critical
  likelyadjust, layout, schedule, late_nilcheck, flagalloc, regalloc
  loop_rotate, stackframe, trim
  <flag> is one of on, off, debug, mem, time, test, stats, dump
  <value> defaults to 1
  <function_name> is required for "dump", specifies name of function to dump after <phase>
  Except for dump, output is directed to standard out; dump appears in a file.
  Phase "all" supports flags "time", "mem", and "dump".
  Phases "intrinsics" supports flags "on", "off", and "debug".
  Interpretation of the "debug" value depends on the phase.
  Dump files are named <phase>__<function_name>_<seq>.dump.

To this:

  compile: PhaseOptions usage:

      go tool compile -d=ssa/<phase>/<flag>[=<value>|<function_name>]

  where:

  - <phase> is one of:
      check, all, build, intrinsics, early_phielim, early_copyelim
      early_deadcode, short_circuit, decompose_user, opt, zero_arg_cse
      opt_deadcode, generic_cse, phiopt, nilcheckelim, prove
      decompose_builtin, softfloat, late_opt, generic_deadcode, check_bce
      branchelim, fuse, dse, writebarrier, insert_resched_checks, lower
      lowered_cse, elim_unread_autos, lowered_deadcode, checkLower
      late_phielim, late_copyelim, tighten, phi_tighten, late_deadcode
      critical, likelyadjust, layout, schedule, late_nilcheck, flagalloc
      regalloc, loop_rotate, stackframe, trim

  - <flag> is one of:
      on, off, debug, mem, time, test, stats, dump

  - <value> defaults to 1

  - <function_name> is required for the "dump" flag, and specifies the
    name of function to dump after <phase>

  Phase "all" supports flags "time", "mem", and "dump".
  Phase "intrinsics" supports flags "on", "off", and "debug".

  If the "dump" flag is specified, the output is written on a file named
  <phase>__<function_name>_<seq>.dump; otherwise it is directed to stdout.

Also add a few examples at the bottom.

Fixes #20349

Change-Id: I334799e951e7b27855b3ace5d2d966c4d6ec4cff
Reviewed-on: https://go-review.googlesource.com/110062
Reviewed-by: Josh Bleecher Snyder <josharian@gmail.com>

diff --git a/src/cmd/compile/internal/ssa/compile.go b/src/cmd/compile/internal/ssa/compile.go
index bd90235682204d74939ebd130f3871e3fdaa6903..2f15cfd1e7aa98ada61b6e75eab6123a2aca0dbe 100644 (file)
--- a/src/cmd/compile/internal/ssa/compile.go
+++ b/src/cmd/compile/internal/ssa/compile.go
@@ -192,29 +192,55 @@ var BuildDump string // name of function to dump after initial build of ssa
 func PhaseOption(phase, flag string, val int, valString string) string {
        if phase == "help" {
                lastcr := 0
-               phasenames := "check, all, build, intrinsics"
+               phasenames := "    check, all, build, intrinsics"
                for _, p := range passes {
                        pn := strings.Replace(p.name, " ", "_", -1)
                        if len(pn)+len(phasenames)-lastcr > 70 {
-                               phasenames += "\n"
+                               phasenames += "\n    "
                                lastcr = len(phasenames)
                                phasenames += pn
                        } else {
                                phasenames += ", " + pn
                        }
                }
-               return "" +
-                       `GcFlag -d=ssa/<phase>/<flag>[=<value>|<function_name>]
-<phase> is one of:
+               return `PhaseOptions usage:
+
+    go tool compile -d=ssa/<phase>/<flag>[=<value>|<function_name>]
+
+where:
+
+- <phase> is one of:
 ` + phasenames + `
-<flag> is one of on, off, debug, mem, time, test, stats, dump
-<value> defaults to 1
-<function_name> is required for "dump", specifies name of function to dump after <phase>
-Except for dump, output is directed to standard out; dump appears in a file.
+
+- <flag> is one of:
+    on, off, debug, mem, time, test, stats, dump
+
+- <value> defaults to 1
+
+- <function_name> is required for the "dump" flag, and specifies the
+  name of function to dump after <phase>
+
 Phase "all" supports flags "time", "mem", and "dump".
-Phases "intrinsics" supports flags "on", "off", and "debug".
-Interpretation of the "debug" value depends on the phase.
-Dump files are named <phase>__<function_name>_<seq>.dump.
+Phase "intrinsics" supports flags "on", "off", and "debug".
+
+If the "dump" flag is specified, the output is written on a file named
+<phase>__<function_name>_<seq>.dump; otherwise it is directed to stdout.
+
+Examples:
+
+    -d=ssa/check/on
+enables checking after each phase
+
+    -d=ssa/all/time
+enables time reporting for all phases
+
+    -d=ssa/prove/debug=2
+sets debugging level to 2 in the prove pass
+
+Multiple flags can be passed at once, by separating them with
+commas. For example:
+
+    -d=ssa/check/on,ssa/all/time
 `
        }