[clang-tidy] Update docs for bugprone-use-after-moveuse-after-move-docs

- Create a separate section on silencing erroneous warnings and add more material to it
- Add note that the check is flow-sensitive but not path-sensitive

1 files changed, 33 insertions, 3 deletions

diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone-use-after-move.rst b/clang-tools-extra/docs/clang-tidy/checks/bugprone-use-after-move.rst
index 9fde912837d8..aab7cfd0ccd4 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone-use-after-move.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone-use-after-move.rst
@@ -24,6 +24,9 @@ move and before the use. For example, no warning will be output for this code:
     str = "Greetings, stranger!\n";
     std::cout << str;
 
+Subsections below explain more precisely what exactly the check considers to be
+a move, use, and reinitialization.
+
 The check takes control flow into account. A warning is only emitted if the use
 can be reached from the move. This means that the following code does not
 produce a warning:
@@ -60,7 +63,12 @@ mutually exclusive. For example (assuming that ``i`` is an int):
     }
 
 In this case, the check will erroneously produce a warning, even though it is
-not possible for both the move and the use to be executed.
+not possible for both the move and the use to be executed. More formally, the
+analysis is `flow-sensitive but not path-sensitive
+<https://en.wikipedia.org/wiki/Data-flow_analysis#Sensitivities>`_.
+
+Silencing erroneous warnings
+----------------------------
 
 An erroneous warning can be silenced by reinitializing the object after the
 move:
@@ -75,8 +83,30 @@ move:
       std::cout << str;
     }
 
-Subsections below explain more precisely what exactly the check considers to be
-a move, use, and reinitialization.
+If you want to avoid the overhead of actually reinitializing the object, you can
+create a dummy function that causes the check to assume the object was
+reinitialized:
+
+.. code-block:: c++
+
+    template <class T>
+    void IS_INITIALIZED(T&) {}
+
+You can use this as follows:
+
+.. code-block:: c++
+
+    if (i == 1) {
+      messages.emplace_back(std::move(str));
+    }
+    if (i == 2) {
+      IS_INITIALIZED(str);
+      std::cout << str;
+    }
+
+The check will not output a warning in this case because passing the object to a
+function as a non-const pointer or reference counts as a reinitialization (see section
+`Reinitialization`_ below).
 
 Unsequenced moves, uses, and reinitializations
 ----------------------------------------------