Раньше, когда я не пользовался IDE, я частенько бегал в гугл. Держать в голове всю документацию php - нереально, никогда не запомнишь всего и вся. А чтобы найти нужную функцию или класс в доке - нужно: интернет, набрать в гугле запрос, перейти к функции и только после этого начать читать, потом прочитав - вернуться в редактор. В день таких операций может быть десятки, они могут отнимать в день достаточно много времени. Очень много. Если еще посчитать время, которое теряется при отвлечении от кода, то оно может измеряться десятками минут, и даже часами!

Но на подобных операциях можно легко сэкономить время. Достаточно иметь под рукой IDE. Представим типичную ситуацию - вы пишете что-то, вам надо воспользоваться какой-то функцией, например, str_replace(). Как сделаю я в phpStorm - просто зажму ctrl и наведу мышкой на стандартную функцию. Если мне будет недостаточно списка параметров, то я нажму ctrl+Q (или F1 на маке), и мне откроется полная документация по функции с описанием, из которого, если мне надо, я смогу перейти к странице оф. документации

Удобно - не правда ли? Кто-то скажет - дока на английском, не удобно. Я отвечу - учите английский, пригодится 🙂 современному разработчику без английского никуда. Другие IDE, например тот же Netbeans, имеет встроенную русскую справку по стандартным функциям.

Что самое интересное - подобная функциональность возможно благодаря движку phpStorm. Любой phpDoc комментарий будет мгновенно подцеплен, и аналогичным же образом его можно просмотреть при любом вызове функции. Благо, сделать phpDoc комментарий в IDE - дело нескольких секунд:

Набираем /** и жмем Enter - все, самое сложное уже сделано, осталось оставить небольшой коммент.
И теперь вам никакого труда не стоит узнать, какие типы переменных принимает функция, какой тип переменных функция возвращает, можете просмотреть комментарий, оставленный разработчиком к функции. Поверьте - хороший комментарий к большой и сложной функции может сэкономить очень много времени вашему коллеге, да и вам самому через некоторое время.

А документировать с помощью phpDoc можно не только функции. Можете документировать свои константы, например. И в любом месте проекта можете быстренько просмотреть, для чего данная константа нужна

Мораль - документирование реально упрощает жизнь. Не только вам, но и вас окружающим, поэтому берем, и идем на оф. сайт phpDocumentor и изучаем, как должны выглядеть комменты

Что интересно - в phpStorm документация к стандартному php коду сделана по аналогии с тем, как она работает для ваших функций. В ядре продукта есть обычный файл со списком функций, где в phpDoc комментариях для них расписана официальная документация. Вот так то

Спасибо Ивану за «пинок», с его подачи написал