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);
}
}
?>
ПримечанияПравить
- ↑ Release 2.7.0
- ↑ Сравнение см. 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 (англ.) — Документация
См. такжеПравить
Это статья-заготовка о компьютерных языках. Помогите Википедии, дополнив эту статью, как и любую другую. |