13-08-2023
Тип | |
---|---|
Разработчик |
Joshua Eichorn |
Операционная система |
кроссплатформенная |
Последняя версия |
1.4.2 (31.03.2008[1]) |
Лицензия | |
Сайт |
Официальный сайт |
phpDocumentor — это система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, , man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является Doxygen[2].
Содержание |
Может использоваться как из командной строки, так и с помощью Web-интерфейса[3]. Понимает синтаксис 4-й и 5-й версий языка PHP. Распространяется под лицензией LGPL.
В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам.
Комментарии для phpDocumentor получили названия Doc-блоки (англ. DocBlock comments). Они оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
/**
* Имя или краткое описание объекта
*
* Развернутое описание
*
* @имя_дескриптора значение
* @return тип_данных
*/
Все другие комментарии игнорируются системой.
В описаниях допускается использование некоторых дескрипторов HTML:
Слова начинающиеся с символа «@» используются для написания команд парсера и называются дескрипторами (тегами, ярлыками). Стандартные дескрипторы стоят в начале строки. Дескрипторы находящиеся внутри строки заключаются в фигурные скобки {} и называются инлайн (англ. 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); } } ?>
Это заготовка статьи о компьютерных языках. Вы можете помочь проекту, исправив и дополнив её. |
PhpDocumentor.