PossiblyNullArgument: Adding common problem cases and possible solutions

docs/running_psalm/issues/PossiblyNullArgument.md

@@ -5,6 +5,44 @@ Emitted when calling a function with a value that’s possibly null when the fun
 ```php
 <?php
 
-function foo(string $s) : void {}
+function foo(string $s): void {}
 foo(rand(0, 1) ? "hello" : null);
 ```
+
+## Common Problem Cases
+
+### Using a Function Call inside `if`
+
+```php
+if (is_string($cat->getName()) {
+    foo($cat->getName());
+}
+```
+This fails since it's not guaranteed that subsequent calls to `$cat->getName()` always give the same result.
+
+#### Possible Solutions
+
+* Use a variable:
+    ```php
+    $catName = $cat->getName();
+    if (is_string($catName) {
+        foo($catName);
+    }
+    unset($catName);
+    ```
+* Add [`@psalm-mutation-free`](../../annotating_code/supported_annotations.md#psalm-mutation-free) to the declaration of the function
+
+### Calling Another Function After `if`
+
+```php
+if (is_string($cat->getName()) {
+    changeCat();
+    foo($cat->getName());
+}
+```
+This fails since psalm cannot know if `changeCat()` does actually modify `$cat`.
+
+#### Possible Solutions
+
+* Add [`@psalm-mutation-free`](../../annotating_code/supported_annotations.md#psalm-mutation-free) to the declaration of the other function (here: `changeCat()`) too
+* Use a variable: See above