Choose a common tag to suggest that the result of a function/closure/method should be used

[TysonAndre]

Psalm has psalm-pure/psalm-external-mutation-free/psalm-internal-mutation-free. https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md#psalm-mutation-free

Phan has @phan-side-effect-free, which isn't as strict - it allows functions that aren't deterministic such as rand(), file_get_contents(), microtime(), etc.

It would be useful to have a common annotation for at least one of the following options:

1. The return value of this function must be used (e.g. opening a resource)

   @must-use (haven't put much thought into the name)

2. The return value of this function must be used, and this (should be treated as if) there are no side effects internally or externally (e.g. computing the Nth prime)

   Ideas: @[effectively-]side-effect-free, @x-pure, etc.