PhpDocumentor
phpDocumentor | |
---|---|
Тип | Генератор документации |
Разработчик | Joshua Eichorn |
Написана на | PHP |
Операционная система | кроссплатформенная |
Последняя версия | 3.4.1 (25.08.2023[1]) |
Лицензия | LGPL |
Сайт | phpdoc.org |
phpDocumentor — система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является Doxygen[2].
Может использоваться как из командной строки, так и с помощью Web-интерфейса[3]. Понимает синтаксис 4-й и 5-й версий языка PHP. Распространяется под лицензией LGPL.
Основные концепции
В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам.
Синтаксис
Комментарии для phpDocumentor получили названия Doc-блоки (англ. DocBlock comments). Они оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */
Все другие комментарии игнорируются системой.
В описаниях допускается использование некоторых дескрипторов HTML:
- <b> — жирное начертание;
- <code> — код;
- <br> — разрыв строки;
- <i> — курсив;
- <kbd> — сочетание клавиш;
- <li> — элемент списка;
- <ol> — нумерованный список;
- <p> — абзац;
- <pre> — форматированный текст;
- <samp> — пример;
- <ul> — маркированный список;
- <var> — имя переменной.
Дескрипторы
Слова, начинающиеся с символа «@», используются для написания команд парсера и называются дескрипторами (тегами, ярлыками). Стандартные дескрипторы стоят в начале строки. Дескрипторы, находящиеся внутри строки, заключаются в фигурные скобки {} и называются инлайн (англ. inline tag) дескрипторами.
/** * Ошибка! @error стандартный дескриптор в строке * Это инлайн {@inlinetag} дескриптор * @standardtag - это стандартный дескриптор */
Список дескрипторов phpDocumentor | ||
---|---|---|
Дескриптор | Описание | Пример |
@author | Автор | /** * Sample File 2, phpDocumentor Quickstart * * Файл из документации к phpDocumentor * демонстрирующий способы комментирования. * @author Greg Beaver <[email protected]> * @version 1.0 * @package sample * @subpackage classes */ |
@version | Версия кода | |
@package | Указывает пакет к которому относится код | |
@subpackage | Указывает подпакет | |
@global | Описание глобальных переменных | /** * DocBlock для глобальной переменной * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной * или глобальная переменная, в этом случае необходимо указать ее имя * @name $myvar */ $GLOBALS['myvar'] = 6; |
@name | Имя, метка | |
@staticvar | Описание статических переменных | /** * @staticvar integer $staticvar * @return возвращает целое значение */ |
@return | Описание возвращаемого значения | |
@todo | Заметки для последующей реализации. | /** * DocBlock с вложенными списками * @todo Простой TODO список * - item 1 * - item 2 * - item 3 * @todo Вложенный TODO список * <ol> * <li>item 1.0</li> * <li>item 2.0</li> * <ol> * <li>item 2.1</li> * <li>item 2.2</li> * </ol> * <li>item 3.0</li> * </ol> */ |
@link | Ссылка | /** * Это пример {@link http://www.example.com встроенной гиперссылки} */ |
@deprecated (@deprec) | Описание устаревшего блока | /** * @deprecated описание * @deprec синоним для deprecated */ |
@example | Пример | /** * @abstract * @access public или private * @copyright Имя дата * @example /path/to/example * @ignore * @internal закрытая информация для специалистов * @param тип [$varname] описание входного параметра * @return тип описание возвращаемого значения * @see имя другого элемента (ссылка) * @since версия или дата * @static */ |
@see | Ссылка на другое место в документации | |
Другие дескрипторы | ||
@copyright · @license · @filesource · @category · @since · @abstract · @access · @example · @ignore · @internal · @static · @throws · @uses · @tutorial |
Пример описания класса
<?php /** * Название (имя) класса * * Полное описание * * @author Ф.И.О. <e-mail> * @version 1.0 */ class ExampleClass { /** * Свойство класса * * @var float Число с плавающей точкой */ public $exampleVar = 3.5; /** * Метод класса * * @param string $text строка * @return string */ public function escape($text) { return addslashes($text); } } ?>
Примечания
- ↑ Release v3.4.1 · phpDocumentor/phpDocumentor · GitHub
- ↑ Сравнение см. Doxygen vs phpDocumentor Архивная копия от 7 мая 2017 на Wayback Machine и Doxygen vs phpDocumentor, часть 2. INPUT_FILTER Архивная копия от 7 мая 2017 на Wayback Machine
- ↑ phpDocumentor Manual (неопр.). Дата обращения: 12 апреля 2010. Архивировано из оригинала 15 мая 2006 года.
Ссылки
- www.phpdoc.org Архивная копия от 12 февраля 2009 на Wayback Machine (англ.) — официальный сайт
- http://manual.phpdoc.org Архивная копия от 15 мая 2006 на Wayback Machine (англ.) — Документация