Русская Википедия: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 - это стандартный дескриптор
*/
Пример описания класса
<?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 — Документация
См. также