Кстати о phpDoc — есть его полная поддержка. После написания функции или метода, например, достаточно написать над функцией строку  /** и нажать tab — основной блок для phpDoc комментария будет сгенерирован. Вам нужно будет только добавить описание для вашей сущности и задать типы переменных (в случае с функциями). В случае изменения функции, ее параметров или чего либо, что могло бы повлиять на phpDoc — редактор подсветит блок комментария и предложит обновить его.

Вообще говоря — phpStorm всегда будет помогать вам, подсвечивая или подчеркивая какие-то странные на его взгляд моменты. Лучше обращать на них внимание и следовать рекомендациям.