phpDocumentor
phpDocumentor — это система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является Doxygen[2].
| phpDocumentor | |
|---|---|
| Тип | Генератор документации |
| Разработчик | Joshua Eichorn |
| Написана на | PHP |
| Операционная система | кроссплатформенная |
| Последняя версия | 2.7.0 (20.08.2014[1]) |
| Лицензия | LGPL |
| Сайт | phpdoc.org |
Может использоваться как из командной строки, так и с помощью 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 <cellog@php.net>
* @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);
}
}
?>
Примечания
Ссылки
- www.phpdoc.org (англ.) — официальный сайт
- http://manual.phpdoc.org (англ.) — Документация