PhpDocumentor 📖 Wikipedia

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 - это стандартный дескриптор
 */

/**
 * Sample File 2, phpDocumentor Quickstart
 * 
 * Файл из документации к phpDocumentor
 * демонстрирующий способы комментирования.
 * @author Greg Beaver <cellog@php.net>
 * @version 1.0
 * @package sample
 * @subpackage classes
 */

/**
 * DocBlock для глобальной переменной
 * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной
 * или глобальная переменная, в этом случае необходимо указать ее имя
 * @name $myvar
 */ 
$GLOBALS['myvar'] = 6;

/**
* @staticvar integer $staticvar
* @return возвращает целое значение
*/

/**
 * 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 http://www.example.com встроенной гиперссылки}
*/

/**
 * @deprecated   описание
 * @deprec       синоним для deprecated
 */

/**
 * @abstract
 * @access       public или private
 * @copyright    Имя дата
 * @example      /path/to/example
 * @ignore
 * @internal     закрытая информация для специалистов
 * @param        тип [$varname] описание входного параметра
 * @return       тип описание возвращаемого значения
 * @see          имя другого элемента (ссылка)
 * @since        версия или дата
 * @static
 */

<?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 Архивная копия от 12 февраля 2009 на Wayback Machine (англ.) — официальный сайт
• http://manual.phpdoc.org Архивная копия от 15 мая 2006 на Wayback Machine (англ.) — Документация

• Javadoc
• JSDoc
• Doxygen