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

Содержание

Текст

Текст

Текст

Текст

Текст

Текст

Текст

Текст

Текст

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

Может использоваться как из командной строки, так и с помощью Web-интерфейса. Понимает синтаксис 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);
   }
}
?>

Ссылки

• www.phpdoc.org Шаблон:WaybackШаблон:Ref-en — официальный сайт
• http://manual.phpdoc.org Шаблон:WaybackШаблон:Ref-en — Документация

См. также

• Javadoc
• JSDoc
• Doxygen