phpDocumentor PHP 25.11.2008

phpDocumentor предоставляет автоматическое документирование исходников вашего php кода.

Коротко о возможностях:

• вывод документации в HTML, PDF, CHM, XML DocBook
• два режима управления: через веб интерфейс и командную строку
• настраиваемый вывод в шаблонах на базе Smarty
• автоматическое связывание, диаграмма наследования классов и умное переопределение
• настраиваемая подсветка кода, перекрестные ссылки (phpxref)
• парсинг README/CHANGELOG/INSTALL/FAQ файлов и включение их в документацию
• генерация списков todo из @todo тегов в коде
• легкое расширение документации для специфических нужд с помощью Converter
• конфигурационный файл позволяет настраивать повторяющиеся и рутинные задачи
• несколько HTML шаблонов оформления документации
• вывод документации в HTML, PDF, CHM, XML DocBook
• два режима управления: через веб интерфейс и командную строку
• настраиваемый вывод в шаблонах на базе Smarty
• автоматическое связывание, диаграмма наследования классов и умное переопределение
• настраиваемая подсветка кода, перекрестные ссылки (phpxref)
• парсинг README/CHANGELOG/INSTALL/FAQ файлов и включение их в документацию
• генерация списков todo из @todo тегов в коде
• легкое расширение документации для специфических нужд с помощью Converter
• конфигурационный файл позволяет настраивать повторяющиеся и рутинные задачи
• несколько HTML шаблонов оформления документации

Инсталляция:

Необходимая версия PHP для работы 4.3.0 (начиная с этой версии есть полная поддержка php-cli) и выше. Существует два способа установки phpDocumentor, первый – скачивание и распаковка архива с phpDocumentor, второй – установка через PERR инсталер.

Есть два режима работы: через командную строку и web интерфейс.

Через командную строку:

под Windows: C:>php.exe "C:PathTophpdoc" -t targetdir -o HTML:default:default -d parsedir

где targetdir - директория, в которую будет помещена сгенерированная документация parsedir - директория, в которой лежат исходники полезные ключи:

-ti – название проекта -dn - название пакета по-умолчанию -pp on – добавление в документацию private элементов

под Linux: phpdoc -t targetdir -o HTML:default:default -d parsedir

Через web интерфейс:

Открываем url, в который был установлен phpDocumentor, например http://localhost/phpdoc/index.html. На вкладке Files указываем файлы и директории для парсинга, также можно указать файлы для исключения (поддерживаются шаблоны поиска). На вкладке Output указываем путь к папке, в которую сгенерируется документация и желаемый вид оформления. На вкладке Options можно дополнительно указать заголовок генерируемой документации, имя пакета, включении в парсинг private переменных и т.д.

Примеры оформления:

Описания (DocBlock) содержатся в многострочных комментариях, которые могут содержать текстовое описание элементов для документирования и специальные ключевые слова (теги), которые начинаются с @.

/**
* Класс для управления коллайдером
*
* @package MyCollayder
* @author proft
* @copyright 2008
*
* создание ссылки на другой класс::метод
* @see class::$property
*
* создание двусторонней ссылки между двумя элементами (например класс, метод)
* @uses Support
*/

class MyCollayder {

/**
* Пример указания типа свойства.
* @var string
*/

public $state = 'on';

/**
* Пример описания метода. Пример создания ссылки на другой метод {@link Support::getAssistance()}
* Пример ссылки на внешний источник с URL и описанием {@link http://www.google.com Search in google}
*
* @param $theState string Состояние коллайдера
* @return bool true если коллайдер запустился, иначе - false
*/

public function init($theState) {   }

Дополнительное описание: manual.phpdoc.org

Дополнение к Vim для вставки phpDocumentor заготовок:

1. Скачиваем phpDocumentor for Vim, например в ~/.vim/
2. В .gvimrc добавляем:

         source ~/.vim/php-doc.vim
         inoremap :call PhpDocSingle()i
         nnoremap :call PhpDocSingle()
         vnoremap :call PhpDocRange()
   

3. Теперь при наведении курсора на метод/свойство и нажатии Ctrl+P автоматически генерируется phpDocumentor заготовка с тегами и переменными, в которую останется только дописать описание