PHPDoc: различия между версиями
[отпатрулированная версия] | [отпатрулированная версия] |
м откат правок 195.222.76.153 (обс) к версии Addbot |
Cheops (обсуждение | вклад) Объединение статей |
||
Строка 1: | Строка 1: | ||
<code><nowiki>{{К объединению|2015-12-20|PHPDoc|phpDocumentator}}</nowiki></code> |
|||
'''PHPDoc''' — это адаптация популярного [[Генератор документации|генератора документации]] [[Javadoc]] для использования с [[PHP]]. Имеет формальный стандарт для комментирования [[PHP]] кода. PHPDoc поддерживает как [[Объектно-ориентированное программирование|объектно-ориентированный]], так и [[Процедурное программирование|процедурный]] код в документах. |
'''PHPDoc''' — это адаптация популярного [[Генератор документации|генератора документации]] [[Javadoc]] для использования с [[PHP]]. Имеет формальный стандарт для комментирования [[PHP]] кода. PHPDoc поддерживает как [[Объектно-ориентированное программирование|объектно-ориентированный]], так и [[Процедурное программирование|процедурный]] код в документах. |
||
Версия от 14:05, 20 декабря 2015
{{К объединению|2015-12-20|PHPDoc|phpDocumentator}}
PHPDoc — это адаптация популярного генератора документации Javadoc для использования с PHP. Имеет формальный стандарт для комментирования PHP кода. PHPDoc поддерживает как объектно-ориентированный, так и процедурный код в документах.
Компоненты PHPDoc
Doc-блоки
Doc-блоки (англ. DocBlock comments) — это многострочные комментарии в стиле языка Си, располагаемые перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
Пример Doc-блока для функции foo():
/**
* Это Doc-блок
*/
function foo()
{
}
Применение
При разработке своих больших проектов, все тонкости которых невозможно держать в голове, ровно как и при доработке чужих проектов, часто приходится подсматривать в ранее написанный код. Это позволяет точнее представлять себе и возвращаемые, создаваемые объекты и что с ними можно делать. Учитывая, что в 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/ — сайт проекта
- Один из примеров применения на сайте Хабрахабр.
Эта статья слишком короткая. |