time

phpDocumentor

phpdoc.jpg 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 заготовка с тегами и переменными, в которую останется только дописать описание

blog comments powered by Disqus