Лучшие вопросы
Таймлайн
Чат
Перспективы
PhpDocumentor
Из Википедии, свободной энциклопедии
Remove ads
phpDocumentor — система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является Doxygen[2].
Может использоваться как из командной строки, так и с помощью Web-интерфейса[3]. Понимает синтаксис 4-й и 5-й версий языка PHP. Распространяется под лицензией LGPL.
Remove ads
Основные концепции
Суммиров вкратце
Перспектива
В основе работы системы лежит парсинг логической структуры 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);
}
}
?>
Remove ads
Примечания
Ссылки
См. также
Wikiwand - on
Seamless Wikipedia browsing. On steroids.
Remove ads