PHPDoc

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

PHPDoc — адаптированный стандарт документирования Javadoc для использования в PHP.

Описание[править | править код]

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

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

phpDocumentor — это приложение, способное анализировать исходный PHP код и комментарии DocBlock для создания полного набора документации по API[2].

Компоненты PHPDoc[править | править код]

Doc-блоки[править | править код]

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

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

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

Возможности PHPDoc[править | править код]

  1. Поддержка последней версии PHP
  2. Работа с классами диаграммы UML
  3. Полнотекстовый поиск
  4. Поддержка CI из коробки
  5. Больше контроля с DocBlocks

Версии PHPDoc[править | править код]

Текущая версия PHPDocumentator 3, Репозиторий

Функции[править | править код]

  • Совместимость с PHP 7.0+ , полная поддержка пространств имен, циклов и многое другое.
  • Docblock над типами , docblocks более явный в отношении типов, не все форматы поддерживаются php.
  • Отображает любой тег , некоторые теги добавляют дополнительные функции в phpDocumentor (например, @link).
  • Низкое использование памяти, пиковое использование памяти для небольших проектов составляет менее 20 МБ, для средних проектов — 40 МБ, а для крупных фреймворков — 100 МБ.
  • Инкрементный синтаксический анализ. При сохранении файла структуры из предыдущего запуска, осуществляется дополнительный прирост производительности до 80% в дополнение к упомянутому выше увеличению скорости обработки.
  • Простое создание шаблона, даёт возможность вызвать 1 задачу и отредактировать 3 файла.
  • Двухэтапный процесс : phpDocumentor сначала создает кеш со структурой приложения перед созданием вывода. Позволяет использовать собственные инструменты или средства форматирования.
  • Общая поддержка, с более статическим анализом в php типы стали сложнее. phpDocumentor понимает эти типы. И будет отображать их как типы первого класса[2].

Применение[править | править код]

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

Ссылки[править | править код]

Примечания[править | править код]

  1. fig-standards/phpdoc.md · phpDocumentor/fig-standards // GitHub. Дата обращения: 20 декабря 2015. Архивировано 31 марта 2016 года.
  2. 1 2 Docker Hub. hub.docker.com. Дата обращения: 24 сентября 2022.