[llvm] [docs][passes] Update documentation of Analysis and Transform Passes (PR #80835)

[Björn Pettersson via llvm-commits]

https://github.com/bjope updated https://github.com/llvm/llvm-project/pull/80835

>From b8d20bd1fb2164f312600a9f31c1ad638d9dc3cd Mon Sep 17 00:00:00 2001
From: Bjorn Pettersson <bjorn.a.pettersson at ericsson.com>
Date: Wed, 31 Jan 2024 17:44:40 +0100
Subject: [PATCH] [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.
---
 llvm/docs/Passes.rst | 56 +++++++++++++-------------------------------
 1 file changed, 16 insertions(+), 40 deletions(-)

diff --git a/llvm/docs/Passes.rst b/llvm/docs/Passes.rst
index 0d0353ed6b611b..faff856f93ff96 100644
--- a/llvm/docs/Passes.rst
+++ b/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
@@ -199,8 +202,9 @@ information query.
 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
 ---------------------------------------