Магнитогорская группа пользователей Linux

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

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

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

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


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


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


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

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

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

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

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

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

Слайд №1

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

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

Слайд №3

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

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

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

Слайд №4

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

Слайд №5

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

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