Аннотация @return используется для указания типа возвращаемого значения функции или метода. Смысл этой аннотации заключается в том, чтобы документировать ожидаемый тип данных, который будет возвращен из функции, чтобы другие разработчики могли лучше понять, что функция возвращает и какие данные она возвращает.
Для корректного описания возвращаемого типа массива в аннотации функции для переменной "discount" нужно указать, что "discount" может быть целым числом или null. Поэтому Psalm требует установить знак "?" перед int и использовать "int<min, max>|null", чтобы указать, что переменная "discount" может быть либо целым числом в определенном диапазоне, либо null. Это более точное и строгое описание типа данных, чтобы избежать ошибок типизации данных и улучшить анализ статического типа.