As I said above, `|null` is *very* different from "optional variable". We need to document every single type a variable is allowed to be. If the variable is allowed to be null, it definitely needs to be documented as `|null`. The fact that it's optional belongs should be documented in another way. If my variable was `$foo = 'bar'`, I would document is as `string`. If my variable was expected to be a string, but had a boolean default value: `$foo = false`, I would document it as `string|boolean`!