From ce25b39b5dd4150dc87b996899f3566f19acfa9e Mon Sep 17 00:00:00 2001
From: Jeremiasz Major <jrh.mjr@gmail.com>
Date: Fri, 8 Apr 2022 00:30:23 +0200
Subject: [PATCH] Document `@psalm-ignore-variable-*`

---
 docs/annotating_code/supported_annotations.md | 25 +++++++++++++++++++
 tests/DocumentationTest.php                   |  2 --
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/annotating_code/supported_annotations.md b/docs/annotating_code/supported_annotations.md
index 06077c3e705..0337e9e7d41 100644
--- a/docs/annotating_code/supported_annotations.md
+++ b/docs/annotating_code/supported_annotations.md
@@ -553,6 +553,31 @@ Incidentally, it will change the inferred type for the following code:
 ```
 The type of `$a` is `array<array-key, int>` without `@no-named-arguments` but becomes `list<int>` with it, because it excludes the case where the offset would be a string with the name of the parameter
 
+### `@psalm-ignore-variable-property` and `@psalm-ignore-variable-method`
+
+Instructs Psalm to ignore variable property fetch / variable method call when looking for dead code.
+```php
+class Foo
+{
+    // this property can be deleted by Psalter,
+    // as potential reference in get() is ignored
+    public string $bar = 'bar';
+
+    public function get(string $name): mixed
+    {
+        /** @psalm-ignore-variable-property */
+        return $this->{$name};
+    }
+}
+```
+When Psalm encounters variable property, it treats all properties in given class as potentially referenced.
+With `@psalm-ignore-variable-property` annotation, this reference is ignored. 
+
+While `PossiblyUnusedProperty` would be emitted in both cases, using `@psalm-ignore-variable-property`
+would allow [Psalter](../manipulating_code/fixing.md) to delete `Foo::$bar`.
+
+`@psalm-ignore-variable-method` behaves the same way, but for variable method calls.
+
 ### `@psalm-yield`
 
 Used to specify the type of value which will be sent back to a generator when an annotated object instance is yielded.
diff --git a/tests/DocumentationTest.php b/tests/DocumentationTest.php
index a3dbc93362a..e55a192e679 100644
--- a/tests/DocumentationTest.php
+++ b/tests/DocumentationTest.php
@@ -76,8 +76,6 @@ class DocumentationTest extends TestCase
         '@psalm-assert-untainted',
         '@psalm-flow',
         '@psalm-generator-return',
-        '@psalm-ignore-variable-method',
-        '@psalm-ignore-variable-property',
         '@psalm-override-method-visibility',
         '@psalm-override-property-visibility',
         '@psalm-scope-this',