Документирование PHP-кода

Автор: Павел Вязовой

Оригинал: http://vyazovoi.github.com/pages/phpdoc.html

Извините за кривое форматирование, некогда править. Рекомендую смотреть красивый документ здесь: http://vyazovoi.github.com/pages/phpdoc.html
Слайды в pdf брать здесь: http://vyazovoi.github.com/files/phpdoc.pdf




1 Введение






Каким бы хорошим не был код, без комментирев и документации он сложен для
восприятия. В любом случае - считаете вы так или нет, а документировать код придется, особенно если он будет использоваться другими
людьми.



Для удобства программистов существуют специальные комментарии, которые служат для автоматической генерации документации.



Хороший пример правильного комментария - это комментарий, содержащий:




  1. Информацию об авторе модуля/класса/функции - бывает очень полезно в больших и
    сложных проектах, которые пишут большое количество программистов.


  2. Назначение описываемого кода.


  3. Описание возвращаемого значения и входных параметров функции - в имени переменной много информации не уместишь.


  4. Любая другая полезная информация








2 phpdoc






Начнем с теории:



Генератор документации - это программа, которая анализирует исходный код и генерирует
документацию для программистов или для пользователей с такими удобствами как поиск и
глоссарий.



Для того, чтобы анализатор мог считывать дополнительную информацию, нужен стандарт на
документирующие комментарии. Также интегрированные среды разработки могут использовать
такие комментарии для, например, вывода всплывающих подсказок.



Первым стоит упомянуть phpdoc - это адаптация javadoc под php. Написан на
PHP. Популярностью не пользуется, тем не менее его формат комментариев стал стандартом де-факто
для документирования php-кода.



Блок с комментарием называется DocBlock. Вот примеры DocBlock'ов:



Слайд №1



Первый докблок в файле - комментарий для всего файла.



Базовые элементы любого док-блока это короткое описание, развернутое
описание и теги.
Длинное описание отделяется от короткого пустой строкой или точкой.
Развернутое описание может содержать в себе html-форматирование.






2.1 Теги






Слайд №2



Теги это специальные ключевые слова, которые начинаются с символа "собака". Все теги
являются опциональными.







2.2 Пакеты






Пакеты обозначаются тегом "@package". Пакеты объединяют константы, переменные, функции и классы
в группы. Если взять в пример сам PHP - каждый его подключаемый модуль может быть отдельным пакетом.



На этом месте мы закончим с теорией и перейдем к генераторам документации.








3 phpDocumentor






Слайд №3



phpDocumentor является стандартом де-факто для документирования PHP-кода. Как
результат - он поддерживается в большинстве PHP-ориентированных сред разработки, например, в популярном
Zend Studio. Более того, Zend Studio работает корректно только с DocBlock'ами
phpDocumentor.



Надо отметить, что phpDocumentor пока не поддерживает нововведения недавнего PHP версии 5.3.



Что касается кроссплатформенности: т.к. phpDocumentor написан на PHP - он работает везде, где работает PHP.







4 Doxygen






Слайд №4



Первое, что бросается в глаза - большое количество поддерживаемых языков.
Doxygen очень популярен и используется во многих opensource проектах. Среди них такие
проекты как KDE и Mozilla. Из известных PHP-приложений, которые используют Doxygen,
стоит упомянуть Drupal.
Doxygen также поддерживается многими средами разработки. Например Kdevelop и Eclipse (с
помощью стороннего плагина). Но среды, завязанные на PHP, предпочитают phpDocumentor.







5 Сравнение






Слайд №5



Есть у doxygen очевидные плюсы: поддержка нескольких языков и диаграммы связей.



Тем не менее, есть в нем и жирный минус, который я не упомянул ранее: не полная
поддержка PHP, связанная с тем, что doxygen ориентирован на язык си.




Author: Pavel Vyazovoi
<vyazovoi@googlemail.com>


Date: 2010-03-14 21:00:40 YEKT


HTML generated by org-mode 6.34c in emacs 23



RSS-материал RSS-материал