ru PhpDocumentor

phpDocumentor
phpDocumentor
Тип	Генератор документации
Разработчик	Joshua Eichorn
Написана на	PHP
Операционная система	кроссплатформенная
Последняя версия	3.4.1 (25.08.2023)
Лицензия	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 <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 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 (англ.) — Документация

См. также

[1] Release v3.4.1 · phpDocumentor/phpDocumentor · GitHub

[2] Сравнение см. Doxygen vs phpDocumentor Архивная копия от 7 мая 2017 на Wayback Machine и Doxygen vs phpDocumentor, часть 2. INPUT_FILTER Архивная копия от 7 мая 2017 на Wayback Machine

[phpdoc_manual-3] Documentor Manual (неопр.). Дата обращения: 12 апреля 2010. Архивировано из оригинала 15 мая 2006 года.

[1]

[2]

[3]