PHP - автоматизированная документация

Не секрет, что комментарии в коде важны, особенно если вы не единственный, кто работает над ним.
Есть 3 вида комментариев:

Однострочный

//комментарий 1

Такие комментарии удобно использовать посреди большого куска кода, когда надо написать маленькую заметку, либо когда нужно временно закоментировать строчку.

Многострочный

/*комментарий 2.0
* комментарий 2.1
* комментарий 2.2*/

Используются в тех местах кода, где СОВСЕМ не очевидно, что делает код, перед регулярными выражениями, странными и сложными запросами к базе. Звезда в начале строки не обязательна, но генерируется многими средами и способствует читабельности.

DockBlock
При работе над большими и часто меняющимися проектами удобно использовать автоматизированную документацию. Ее суть в том, что нет необходимости пробегаться по огромному кол-ву модулей, чтобы найти комментарий к той или иной функции. Документация генерируется в отдельный от проекта набор файлов, например html.



Для php наиболее известный инструмент для такой документации - phpDocumentor. Программа кроссплатформенная и может быть использована из командной строки или web-интерфейса. Ее работа заключается в парсинге файлов проекта и генерированию документации на  основе DocBlock комментариев в них.

Особенности DockBlock комментариев:

• блок начинается с **
• в начале каждой строки должен быть символ *
• блоки внутри комментария разделяются пустой строкой.
• поддерживают дескрипторы html:  b, i, li, ol, ul, code, kbd - сочетание клавиш, samp - пример, var - переменная.
• имеет свои дескрипторы  - команды парсеру, которые начинаются с @ и находятся в начале строки. Дескрипторы, которые находятся в тексте, а не в начале строки, называются инлайновые и дополнительно заключаются в {}.
  Примеры:
  @package
  @param
  @return
  @var
  @ignore
  @author ...

Пример кода с комментариями:

/** 
* Однострочное описание. 
*  
* Многострочное описание. Это File-level комментарий. 
* На сайте phpDocumentor подробно разбирается, 
* когда комментарий считается file-level, 
* а когда относится к первому объявлению в модуле.
*  
* В File-level разделе целесообразно указывать package,
* версию, автора, лицензию и тд. 
* @version 1.0
* @package simple_classes
*/

/**
* Возвращается методами при успешном завершении
*/
define('METHOD_OK', 1);

/**
* Глобальная переменная.
* @global int $GLOBALS['Item_count']
*/
$GLOBALS['Item_count'] = 0;

/**
* Описание класса.
*/
class SimpleClass
{
   /**
   * Свойство класса
   * 
   * @var 
   */
   var $length = 4.0;
 
   /**
   * Метод класса
   * 
   * @param float $num число для округления
   * @return int
   */
 
   function ($num)
   {
      return (int) round($num, 3);
   }
}
}

Здесь приведен более полный пример DockBlock комментариев.

Установка:
Есть два способа установки phpDoc:

1. Скачивание архива и разархивирование.
   Архив можно скачать с pear.php.net или sourceforge.net, затем разархивировать например в домашнюю директорию /home/user/phpdoc. Для удобства запуска и использования web-интерфейса можно сделать символьные ссылки.
2. Установка через PEAR.
   Библиотека PEAR уже должна быть установлена. Вся установка заключается в выполнении:
   $ pear install PhpDocumentor
   
   Чтобы использовать web-интерфейс перед установкой поменяйте параметр PEAR - data_dir:
   $ pear config-set data_dir /var/www/phpdoc
   data_dir - должна быть поддиректорией вашего web-сервера. Например, создайте директорию phpdoc в  /var/www.

Доступные параметры команды: $ phpdoc --help

Интеграция с NetBeans:
1. Создается небольшой скрипт на запуск утилиты.

#!/bin/bash
# 2 - директории для парсинга
# 3 - куда сохранить результат
phpdoc -d $2 -t $3
echo "$3"
echo "Generating PHP Documentation finished ..."
#открывает получившуюся документацию в браузере
firefox $3/index.html

2. Генерировать документацию можно запуском скрипта вручную или при запуске проекта (run):
Netbeans в свойствах проекта Run Configuration:
  Run as: script (command line)
  PHP interpreter: путь к скрипту
  Arguments: два аргумента - что парсить и куда сохранять.

Что получается в итоге:

PS:
1. Данный вид документации не заменяет мануалы, юзер-гайды и тд.
2. Хорошо откоментированный код != качественный код