phpDocumentor

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

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

Основные концепции[править | править код]

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

Синтаксис[править | править код]

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

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

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

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

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

Дескрипторы[править | править код]

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

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

/**  * Sample File 2, phpDocumentor Quickstart  *   * Файл из документации к phpDocumentor  * демонстрирующий способы комментирования.  * @author Greg Beaver <cellog@php.net>  * @version 1.0  * @package sample  * @subpackage classes  */ 

/**  * DocBlock для глобальной переменной  * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной  * или глобальная переменная, в этом случае необходимо указать ее имя  * @name $myvar  */  $GLOBALS['myvar'] = 6; 

/** * @staticvar integer $staticvar * @return возвращает целое значение */ 

/**  * DocBlock с вложенными списками  * @todo Простой TODO список  *     - item 1  *     - item 2  *     - item 3  * @todo Вложенный TODO список  *     <ol>  *       <li>item 1.0</li>  *       <li>item 2.0</li>  *         <ol>  *           <li>item 2.1</li>  *           <li>item 2.2</li>  *         </ol>  *       <li>item 3.0</li>  *     </ol>  */ 

/** * Это пример {@link http://www.example.com встроенной гиперссылки} */ 

/**  * @deprecated   описание  * @deprec       синоним для deprecated  */ 

/**  * @abstract  * @access       public или private  * @copyright    Имя дата  * @example      /path/to/example  * @ignore  * @internal     закрытая информация для специалистов  * @param        тип [$varname] описание входного параметра  * @return       тип описание возвращаемого значения  * @see          имя другого элемента (ссылка)  * @since        версия или дата  * @static  */ 

Пример описания класса[править | править код]

<?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 Архивная копия от 12 февраля 2009 на Wayback Machine (англ.) — официальный сайт
• http://manual.phpdoc.org Архивная копия от 15 мая 2006 на Wayback Machine (англ.) — Документация

См. также[править | править код]

• Javadoc
• JSDoc
• Doxygen

Это заготовка статьи о компьютерных языках. Помогите Википедии, дополнив её.