PHPDoc — адаптированный стандарт документирования Javadoc для использования в PHP.
Пока стандарт комментирования имеет лишь формальный статус, однако, планируется его закрепление в качестве одного из стандартов разработки PHP-фреймворков, разрабатываемых группой PHP-FIG. Подготавливаемый стандарт получит номер PSR-5[1]. PHPDoc поддерживает как объектно-ориентированный, так и процедурный код в документах.
Для интерпретации кода создана отдельная программа phpDocumentor.
phpDocumentor — это приложение, способное анализировать исходный PHP код и комментарии DocBlock для создания полного набора документации по API[2].
Doc-блоки (англ. DocBlock comments) — это многострочные комментарии в стиле языка Си, располагаемые перед документируемым элементом. Первым символом в комментарии (и в начале строк комментария) должен быть *. Блоки разделяются пустыми строками.
Пример Doc-блока для функции foo():
/**
* @param string $msg string to output
* @author WikiEditor
* @copyright 2016 Wikipedia
* @return string unchanged
*/
function foo($msg = '') {
return $msg;
}
Текущая версия PHPDocumentator 3, Репозиторий
При разработке своих больших проектов, все тонкости которых невозможно держать в голове, ровно как и при доработке чужих проектов, часто приходится подсматривать в ранее написанный код. Это позволяет точнее представлять себе и возвращаемые, создаваемые объекты и что с ними можно делать. Учитывая, что в PHP существует неявное приведение типов, потенциально возможны ошибки, когда производятся операции с объектами разных типов. В языках с сильной типизацией этого не произойдёт — программа просто не скомпилируется.
Для избежания этого и используют PHPDoc и другие подобные технологии. Допустим, имеется код:
...
$eventData = new EventData();
$eventData->sender = $controller;
$eventData->name = 'onDelete';
$eventData->group = 'global';
$eventData->arguments = array('id' => 15);
$eventDispatcher->triggerEvent($eventData);
...
Сторонний разработчик, читая этот код, может не знать, что содержит в себе $controller, однако IDE ему подскажет, если она поддерживает PHPDoc. То есть набрав: $controller-> — мы можем увидеть, что находится внутри. В результате нет необходимости лезть в дебри кода, чтобы выяснить, что передаётся этим объектом и в каком типе.