php5 подарил нам всем много классных и удобных вещей, однако многие из них как обычно у ребят из Зенда - просто недоделаны до конца. Одна из таких вещей - это подобие строгой типизации, точнее возможность такую сделать. Как правило, люди, которые долго программируют в пхп и так пишут типы принимаемых в методах переменных (ну и возвращаемых тоже) - в основном для того, чтобы это подхватывалось IDE - и можно было вызывать посказки и не париться.
Так вот, с приходом php5 на реализацию этого приема в phpDoc казалось бы можно было бы забить. Стало возможным указать тип явно:
public function someFunction(CoolClass $arg)
нет смысла углубляться в то что там будет экспшен, если придет не то - это редкоюзаемо. Вся проблема в том, что в казалось бы такой простой штуке разработчики пхп таки умудрились сделать серьезную недоделку: туда можно написать только имя класса, имя интерфейса (ну это понятно - ибо подсказки), почему-то array, т.е. массив, НО нельзя вписать int или скажем bool. Но это не единственная проблема - также нельзя указать, что же именно возвращает метод, причем вообще нельзя. Так что, этот душевный порыв разработчиков языка так и не нашел своего достойного применения - разве что в качестве выпендрежа (типа смотрите, я и это умею и знаю) ну или редкими энтузиастами, которые основывают свой код на экспешнах, которые полетят в случае если придет не то. Так что, все равно пишем phpDoc-и:
/**
* @param string $categoryId
* @return string
*/
public function getTransactions($categoryId)
ибо они на данный момент незаменимы 