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

Хочу рассмотреть принцип документирования программного PHP кода, основанный на DocBlock (DocBlock comments). Многие называют его стандартом, хотя каких-то авторитетных источников, подтверждающих это, я не нашел. Тем не менее, данный формат комментариев распространен во многих языка. Насколько я понимаю, пришел он из Java и по своему принципу наследует Javadoc. Он прекрасно поддерживается и интерпретируется средами разработки. Также существует немало решений, позволяющих автоматически генерировать документацию на основе таких комментариев.

DocBlock – это многострочный комментарий, требующий соблюдения определенного синтаксиса. В PHP данный способ более известен под другим именем – phpDoc. Оно происходит от названия утилиты phpDocumentor, предоставляющей возможность создавать страницы документации автоматически. Результат ее работы очень похож на официальную документацию PHP.

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

Я хочу привести ряд аргументов, которые, возможно, смогут убедить в том, что хороший комментарий несет пользу прежде всего нам самим. phpDoc блоки позволяют увеличить не только читаемость существующего кода, но и ускорят написание нового за счет использования возможностей IDE.

Синтаксис phpDoc

Весь синтаксис строится на использовании дескрипторов и их значений, обернутых в Си подобный многострочный комментарий.

/**
 * @имя_дескриптора значение_директивы
 * @еще_дескриптор
 *
 */

Наверное, стоит заметить, что каждая строка внутри блока должна начинаться с символа *. Именам дескрипторов предшествует знак @.

phpDoc может описывать не только отдельные участки кода, но и весь файл скрипта, располагаясь в самом начале файла. Такой блок называется заголовочным.

Ниже предлагаю список дескрипторов phpDoc и мои комментарий к ним.

Дескрипторы @access, @final и @abstract были актуальны в PHP 4, но сейчас их можно не использовать, так как они потеряли актуальность с появлением модификаторов доступа и ключевых слов final и abstract.

Каждый docBLock делится на несколько секций:

• заголовок;
• описание;
• список дескрипторов.

Разделителем для секций служит пустая строка.

Примеры использования phpDoc комментариев

Я не хочу приводить синтетические примеры, поэтому заимствую код из популярного фреймворка Zend Framework, который, как мне кажется, имеет самые толковые и подробные блоки комментариев.

Я значительно укоротил многословные описания методов и классов, избегая избыточности в рамках примера. Обратите внимание на общий принцип документирования и на синтаксис дескрипторов.

Использование дескриптора @see

/**
 * @see Zend_Acl_Resource_Interface
 */
require_once 'Zend/Acl/Resource/Interface.php';

Пример блока комментариев для метода класса

/**
 * Removes "deny" restrictions from the ACL
 *
 * @param  Zend_Acl_Role_Interface|string|array     $roles
 * @param  Zend_Acl_Resource_Interface|string|array $resources
 * @param  string|array                             $privileges
 * @uses   Zend_Acl::setRule()
 * @return Zend_Acl Provides a fluent interface
 */
public function removeDeny($roles = null, $resources = null, $privileges = null)
{
    return $this->setRule(self::OP_REMOVE, self::TYPE_DENY, $roles, $resources, $privileges);
}

Свойство класса

/**
 * Role registry
 *
 * @var Zend_Acl_Role_Registry
 */
protected $_roleRegistry = null;

А вот один из примеров подсказок (Eclipse code assist), которые может предлагать среда разработки, в данном случае Eclipse.

Также среда разработки может выводить подсказки, основанные на docBlock. Например, подсказка, появляющаяся при наведении на имя метода Zend_Acl_Role_Registry::add().