phpDocumentor — система документирования исходных текстов на PHP. Имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF. Альтернативой использованию phpDocumentor является DoxygenСравнение см. Doxygen vs phpDocumentor и Doxygen vs phpDocumentor, часть 2. INPUT_FILTER .
Может использоваться как из командной строки, так и с помощью Web-интерфейса. Понимает синтаксис 4-й и 5-й версий языка PHP. Распространяется под лицензией LGPL.
Основные концепции В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам.
Синтаксис Комментарии для phpDocumentor получили названия Doc-блоки (). Они оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
/** * Имя или краткое описание объекта * * Развернутое описание * * @имя_дескриптора значение * @return тип_данных */
Все другие комментарии игнорируются системой.
В описаниях допускается использование некоторых дескрипторов HTML: <b> — жирное начертание; <code> — код; <br> — разрыв строки; <i> — курсив; <kbd> — сочетание клавиш; <li> — элемент списка; <ol> — нумерованный список; <p> — абзац; <pre> — форматированный текст; <samp> — пример; <ul> — маркированный список; <var> — имя переменной.
Дескрипторы Слова, начинающиеся с символа «@», используются для написания команд парсера и называются дескрипторами (тегами, ярлыками). Стандартные дескрипторы стоят в начале строки. Дескрипторы, находящиеся внутри строки, заключаются в фигурные скобки {} и называются инлайн () дескрипторами.
/** * Ошибка! @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 — официальный сайт http://manual.phpdoc.org — Документация
См. также Javadoc JSDoc Doxygen
Категория:Свободные генераторы документации Категория:PHP