Это не официальный сайт wikipedia.org 01.01.2023

phpDocumentor — Википедия

phpDocumentor

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

phpDocumentor
Тип Генератор документации
Разработчик Joshua Eichorn
Написана на PHP
Операционная система кроссплатформенная
Последняя версия 2.7.0 (20.08.2014[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 - это стандартный дескриптор
 */


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

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

ПримечанияПравить

  1. Release 2.7.0
  2. Сравнение см. Doxygen vs phpDocumentor Архивная копия от 7 мая 2017 на Wayback Machine и Doxygen vs phpDocumentor, часть 2. INPUT_FILTER Архивная копия от 7 мая 2017 на Wayback Machine
  3. phpDocumentor Manual  (неопр.). Дата обращения: 12 апреля 2010. Архивировано из оригинала 15 мая 2006 года.

СсылкиПравить

См. такжеПравить