PhpDocumentor

phpDocumentor
Тип Генератор документации
Разработчик Joshua Eichorn
Написана на PHP
Операционная система кроссплатформенная
Последняя версия 3.4.1 (25.08.2023[1])
Лицензия LGPL
Сайт phpdoc.org

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 - это стандартный дескриптор
 */


Список дескрипторов phpDocumentor
Дескриптор Описание Пример
@author Автор 
/**
 * Sample File 2, phpDocumentor Quickstart
 * 
 * Файл из документации к phpDocumentor
 * демонстрирующий способы комментирования.
 * @author Greg Beaver <[email protected]>
 * @version 1.0
 * @package sample
 * @subpackage classes
 */
@version Версия кода
@package Указывает пакет к которому относится код
@subpackage Указывает подпакет
@global Описание глобальных переменных 
/**
 * DocBlock для глобальной переменной
 * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной
 * или глобальная переменная, в этом случае необходимо указать ее имя
 * @name $myvar
 */ 
$GLOBALS['myvar'] = 6;
@name Имя, метка
@staticvar Описание статических переменных 
/**
* @staticvar integer $staticvar
* @return возвращает целое значение
*/
@return Описание возвращаемого значения
@todo Заметки для последующей реализации. 
/**
 * 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 Ссылка 
/**
* Это пример {@link http://www.example.com встроенной гиперссылки}
*/
@deprecated (@deprec) Описание устаревшего блока 
/**
 * @deprecated   описание
 * @deprec       синоним для deprecated
 */
@example Пример 
/**
 * @abstract
 * @access       public или private
 * @copyright    Имя дата
 * @example      /path/to/example
 * @ignore
 * @internal     закрытая информация для специалистов
 * @param        тип [$varname] описание входного параметра
 * @return       тип описание возвращаемого значения
 * @see          имя другого элемента (ссылка)
 * @since        версия или дата
 * @static
 */
@see Ссылка на другое место в документации
Другие дескрипторы
@copyright  · @license  · @filesource  · @category  · @since  · @abstract  · @access  · @example  · @ignore  · @internal  · @static  · @throws  · @uses  · @tutorial

Пример описания класса 

<?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);
   }
}
?>

Примечания

  1. ↑ Release v3.4.1 · phpDocumentor/phpDocumentor · GitHub
  2. ↑ Сравнение см. Doxygen vs phpDocumentor Архивная копия от 7 мая 2017 на Wayback Machine и Doxygen vs phpDocumentor, часть 2. INPUT_FILTER Архивная копия от 7 мая 2017 на Wayback Machine
  3. ↑ phpDocumentor Manual  (неопр.). Дата обращения: 12 апреля 2010. Архивировано из оригинала 15 мая 2006 года.

Ссылки

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

См. также