PhpDocumentor

phpDocumentor — система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является Doxygen^[2].

phpDocumentor
Тип	Генератор документации
Разработчик	Joshua Eichorn
Написана на	PHP
Операционная система	кроссплатформенная
Последняя версия	3.4.1 (25.08.2023[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 <[e-mail]> * @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);
   }
}
?>