[clang-tidy][docs][NFC] Add limitation of variable lifetimes in performance-unnecessary-copy-initialization (#151862)
Addresses https://github.com/llvm/llvm-project/issues/150189.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/performance/unnecessary-copy-initialization.rst b/clang-tools-extra/docs/clang-tidy/checks/performance/unnecessary-copy-initialization.rst
index bb4f42c..0e9d547 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/performance/unnecessary-copy-initialization.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/performance/unnecessary-copy-initialization.rst
@@ -59,3 +59,22 @@
types that don't own the underlying data. Like for `AllowedTypes` above,
regular expressions are accepted and the inclusion of `::` determines whether
the qualified typename is matched or not.
+
+
+Limitations
+-----------
+
+This check does not perform lifetime analysis and may suggest replacing copies
+with const references that could become dangling. Be cautious when the
+referenced object might be invalidated by subsequent operations.
+
+.. code-block:: c++
+
+ void consume(const S&);
+
+ void func(std::vector<S> &Vec) {
+ const auto It = Vec.begin();
+ const S Value(*It); // The warning will suggest making this a const reference.
+ Vec.erase(It); // Container modifications could invalidate references.
+ consume(Value); // Safe with copy, dangling reference otherwise.
+ }
