WikiSort.ru - Не сортированное

PHPDoc — адаптированный стандарт документирования Javadoc для использования в PHP. Пока стандарт комментирования имеет лишь формальный статус, однако, планируется его закрепление в качестве одного из стандартов разработки PHP-фреймворков, разрабатываемых группой PHP-FIG. Подготавливаемый стандарт получит номер PSR-5^[1]. PHPDoc поддерживает как объектно-ориентированный, так и процедурный код в документах.

Для интерпретации кода создана отдельная программа phpDocumentor.

Компоненты PHPDoc

/**
 * @param string $msg string to output
 * @author WikiEditor
 * @copyright 2016 Wikipedia
 * @return string unchanged
 */
function foo($msg = '') {
    return $msg;
}

Применение

При разработке своих больших проектов, все тонкости которых невозможно держать в голове, ровно как и при доработке чужих проектов, часто приходится подсматривать в ранее написанный код. Это позволяет точнее представлять себе и возвращаемые, создаваемые объекты и что с ними можно делать. Учитывая, что в PHP нет строгой типизации, потенциально возможны ошибки, когда сравниваются несравниваемые объекты. Например: строка и число, массив и константа. В некоторых случаях 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. То есть набрав: $eventData->controller-> — мы можем увидеть, что находится внутри атрибута с именем controller. В результате нет необходимости лезть в дебри кода, чтобы выяснить, что передаётся этим объектом и в каком типе.

Ссылки

• http://www.phpdoc.org/ — сайт проекта
• Один из примеров применения на сайте Хабрахабр.

Примечания

Эта статья слишком короткая. Пожалуйста, дополните её ещё хотя бы несколькими предложениями и уберите это сообщение. Если статья останется недописанной, она может быть выставлена к удалению. Для указания на продолжающуюся работу над статьёй используйте шаблон {{subst:L}}.