Перейти к содержимому

15.08.2011

2

Использование php-doc & doxygen для генерации php-документации

Написание документации к коду — задача не самая приятная и радостная, но если вы делаете большой проект и/или участвуете в командной разработке, то, я бы сказал, это вещь просто даже необходимая. Если у вас много разных интерфейсов, классов, функций, методов, с различными парметрами и выходными данными, и с этим приходится работать более чем одному разработчику, очень здорово иметь под рукой описание всех этих самых классов, их атрибутов и параметров, а не бегать каждый раз к разработчику и спрашивать какой параметр что значит. Это ни в коем случае не отменяет того, что сами названия классов, методов и параметров должны иметь осмысленные имена, но не об этом сейчас речь. Сейчас мы поговорим о документировании исходных кодов на php. Я для этих целей использую такой инструмент как Doxygen.

Что такое Doxygen?

Для тех, кто не в курсе что это такое, краткая справка. Как написано на сайте проекта:
Doxygen — это кроссплатформенная система документирования исходных текстов, которая поддерживает C/C++, Objective-C, Python, Java, IDL, PHP, C#, Fortran, VHDL и, частично, D.

Сайт проекта: http://www.stack.nl/~dimitri/doxygen/

Данная утилитка есть под все основные платформы: Windows/Linux/MacOS; а некоторые энтузиасты даже портировали ее под Solaris/OS/2/IRIX/FreeBSD. Так же на сайте имеется прекрасная документация как в pdf-формате, так и в chm-формате. Очень рекомендую с ней ознакомиться.

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

Не буду описывать процесс установки doxygen на комп, потому как это простая процедура, не отличающаяся от установки любого другого приложения.
Для комментирования кода можно использовать несколько стилей, среди которых есть Javadoc, C-style комментарии или же Qt-style комментарии. Я для себя выбрал формат Javadoc по той причине, что он, можно сказать, совместим с форматом phpdoc, и, следовательно, если вы пишите код не в блокноте, а в какой-нибудь среде разработки, которая автоматически понимает phpdoc комментарии, это дает вам сразу возможность видеть подсказки в коде, автоматически подсказывать типы и значения параметров функций и прочие радости жизни. Это проверено в Eclipse IDE (PDT) и Netbeans, но подозреваю, что и в других продвинутых средах разработки это тоже будет работать. Далее будут скриншоты того как это выглядит в Eclipse. А пока приведу пример документирования php-кода:

Если описать класс таким образом, то, например, в Eclipse в любом месте проекта, где вы захотите получить подсказку по методам,свойствам класса, вы увидите примерно следующее:

По моему, это замечательно: сразу видно что делает этот метод, какие параметры он принимает на вход и какого они типа. Ко всему прочему во вьюхе «outline» все функции показываются с типами параметров, что тоже очень приятно.

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

Дополнительные плюшки.

Так же doxygen обладает еще рядом возможностей, среди которых есть генерация графа связи классов. Что в общем и целом очень полезная фича. Причем он показывает граф как «сверху-вниз», то есть для базового класса будут показаны все наследуемые, так и «снизу-вверх», то есть для класса будут показаны все предки. Выглядит это так:


Ну и напоследок, скрины того, как выглядит сгенерированная документация в формате html.
/* Там слева вверху был логотип 🙂 */




Узнайте больше из Web-Разработка
  • Спасибо большое. Ваша статья очень помогла. Хотел бы увидеть более подробное описание языка комментирования php-кода, ибо буржуйский, увы, не знаю.

  • Спасибо за статью! Как раз собрался привести в порядок 1 проект и сделать для него качественную документацию. doxygen — это то что нужно.