[docs][passes] Update documentation of Analysis and Transform Passes

- Added a warning about the pass list being incomplete (and hint about
  "opt -print-passes" listing known passes).
- Replaced legacy PM example involving "opt -analyze" with a proper
  example using -passes option.
- print-function and print-module does not exist with those names
  in the new PM. Since the document has been updated to reflect
  the new PM names earlier, those names were changed into referring to
  function(print) and module(print) instead.
- Resolved some FIXME:s around strip* passes.

Author: bjope

llvm/docs/Passes.rst

@@ -7,6 +7,9 @@ LLVM's Analysis and Transform Passes
 
 Introduction
 ============
+.. warning:: This document is not updated frequently, and the list of passes
+  is most likely incomplete. It is possible to list passes known by the opt
+  tool using ``opt -print-passes``.
 
 This document serves as a high level summary of the optimization features that
 LLVM provides.  Optimizations are implemented as Passes that traverse some
@@ -193,14 +196,15 @@ memory operations it depends on.  It builds on alias analysis information, and
 tries to provide a lazy, caching interface to a common kind of alias
 information query.
 
-``module-debuginfo``: Decodes module-level debug info
------------------------------------------------------
+``print<module-debuginfo>``: Decodes module-level debug info
+------------------------------------------------------------
 
 This pass decodes the debug info metadata in a module and prints in a
 (sufficiently-prepared-) human-readable form.
 
-For example, run this pass from ``opt`` along with the ``-analyze`` option, and
-it'll print to standard output.
+For example, run this pass from ``opt`` along with the
+``-passes='print<module-debuginfo>'`` option, and it'll print to standard
+output.
 
 ``postdomtree``: Post-Dominator Tree Construction
 -------------------------------------------------
@@ -228,18 +232,18 @@ standard error in a human-readable form.
 ``print-cfg-sccs``: Print SCCs of each function CFG
 ---------------------------------------------------
 
-This pass, only available in ``opt``, printsthe SCCs of each function CFG to
+This pass, only available in ``opt``, prints the SCCs of each function CFG to
 standard error in a human-readable fom.
 
-``print-function``: Print function to stderr
---------------------------------------------
+``function(print)``: Print function to stderr
+---------------------------------------------
 
 The ``PrintFunctionPass`` class is designed to be pipelined with other
 ``FunctionPasses``, and prints out the functions of the module as they are
 processed.
 
-``print-module``: Print module to stderr
-----------------------------------------
+``module(print)``: Print module to stderr
+-----------------------------------------
 
 This pass simply prints out the entire module when it is executed.
 
@@ -924,17 +928,8 @@ code size or making it harder to reverse engineer code.
 ``strip-dead-debug-info``: Strip debug info for unused symbols
 --------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-performs code stripping. this transformation can delete:
-
-* names for virtual registers
-* symbols for internal globals and functions
-* debug information
-
-note that this transformation makes code much less readable, so it should only
-be used in situations where the strip utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but only strips debug info for
+unused symbols.
 
 ``strip-dead-prototypes``: Strip Unused Function Prototypes
 -----------------------------------------------------------
@@ -947,32 +942,13 @@ functions).
 ``strip-debug-declare``: Strip all ``llvm.dbg.declare`` intrinsics
 ------------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-This pass implements code stripping.  Specifically, it can delete:
-
-#. names for virtual registers
-#. symbols for internal globals and functions
-#. debug information
-
-Note that this transformation makes code much less readable, so it should only
-be used in situations where the 'strip' utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but only strips
+``llvm.dbg.declare`` intrinsics.
 
 ``strip-nondebug``: Strip all symbols, except dbg symbols, from a module
 ------------------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-This pass implements code stripping.  Specifically, it can delete:
-
-#. names for virtual registers
-#. symbols for internal globals and functions
-#. debug information
-
-Note that this transformation makes code much less readable, so it should only
-be used in situations where the 'strip' utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but dbg info is preserved.
 
 ``tailcallelim``: Tail Call Elimination
 ---------------------------------------