По материалам wiki1, wiki2

PHPDoc — это адаптация популярного генератора документации Javadoc для использования с PHP. Имеет формальный стандарт для комментирования PHP кода. PHPDoc поддерживает как объектно-ориентированный, так и процедурный код в документах.

Doc-блоки (англ. DocBlock comments) — это многострочные комментарии в стиле языка Си, располагаемые перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

Пример Doc-блока для функции foo():

Применение

При разработке своих больших проектов, все тонкости которых невозможно держать в голове, ровно как и при доработке чужих проектов, часто приходится подсматривать в ранее написанный код. Это позволяет точнее представлять себе и возвращаемые, создаваемые объекты и что с ними можно делать. Учитывая, что в PHP нет строгой типизации, потенциально возможны ошибки, когда сравниваются несравниваемые объекты. Например: строка и число, массив и константа. В некоторых случаях PHP даже не выдаёт ошибку при таком сравнении, просто преобразуя типы к одинаковым (если это в принципе возможно). В языках со строгой типизацией этого не произойдёт — программа просто не будет компилироваться.

Для уточнения информации на странице руководства.

Пример использования

Рассмотрим для примера функцию ядра WordPress is_super_admin

Вверху комментарий имеет короткое описание, о том, что эта функция делает (определяет является ли пользователь админом). Ниже комментарий, указывающий когда эта функция была добавлена (в данном случае в версии 3.0.0). Еще ниже информация о единственном параметре, принимаемом функцией, включая тип параметра, за что этот параметр отвечает и факт, что параметр необязательный в данном случае. Последний комментарий обозначает возвращаемое функцией значение (в данном случае функция возвращает true, если пользователь — админ, и false — если нет).