Русская Википедия:PhpDocumentor

Материал из Онлайн справочника
Перейти к навигацииПерейти к поиску

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

Может использоваться как из командной строки, так и с помощью Web-интерфейса[2]. Понимает синтаксис 4-й и 5-й версий языка PHP. Распространяется под лицензией LGPL.

Основные концепции

В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам.

Синтаксис

Комментарии для phpDocumentor получили названия Doc-блоки (Шаблон:Lang-en). Они оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* 
* @имя_дескриптора значение
* @return тип_данных
*/

Все другие комментарии игнорируются системой.

В описаниях допускается использование некоторых дескрипторов HTML:

  • <b> — жирное начертание;
  • <code> — код;
  • <br> — разрыв строки;
  • <i> — курсив;
  • <kbd> — сочетание клавиш;
  • <li> — элемент списка;
  • <ol> — нумерованный список;
  • <p> — абзац;
  • <pre> — форматированный текст;
  • <samp> — пример;
  • <ul> — маркированный список;
  • <var> — имя переменной.

Дескрипторы

Слова, начинающиеся с символа «@», используются для написания команд парсера и называются дескрипторами (тегами, ярлыками). Стандартные дескрипторы стоят в начале строки. Дескрипторы, находящиеся внутри строки, заключаются в фигурные скобки {} и называются инлайн (Шаблон:Lang-en) дескрипторами.

/**
 * Ошибка! @error стандартный дескриптор в строке
 * Это инлайн {@inlinetag} дескриптор
 * @standardtag - это стандартный дескриптор
 */


Шаблон:PhpDocumentor

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

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

Примечания

Шаблон:Примечания

Ссылки

См. также

Шаблон:Compu-lang-stub