phpDocumentor

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

phpDocumentor
Тип Генератор документации
Разработчик Joshua Eichorn
Написана на JavaScript[2]
Операционная система кроссплатформенная
Последняя версия 2.7.0 (20.08.2014[1])
Лицензия LGPL
Сайт phpdoc.org

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

Может использоваться как из командной строки, так и с помощью Web-интерфейса[4]. Понимает синтаксис 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 - это стандартный дескриптор
 */


Пример описания класса[править | править код]

<?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);
   }
}
?>

Примечания[править | править код]

Ссылки[править | править код]

См. также[править | править код]