Комментарии в формате PHPDoc

Система PHPDoc основана на системе Javadoc разработки фирмы Sun, представляющей со­бой простой и удобный способ комментирования всех функций, аргументов, пере­менных и пакетов с тем, чтобы программисты могли легко заимствовать и исполь­зовать их.

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

Примечание

В коде, приведенном обычно нет никаких PHPDoc-комментариев, поскольку лис­тинги кода подробно разбираются в тексте. Но в код приложения, который загружается с веб-сайтов, эти комментарии по возможности включены.

Система PHPDoc основана на том, что перед объявлением каждой функции, класса или переменной вставляется блок комментариев. Его наличие не обяза­тельно — добавляйте комментарии только туда, куда считаете нужным.

Каждый блок комментариев начинается с описания, а за ним могут следовать те или иные параметры. Например, если PHPDoc-комментарий относится к функции, следует описать ее входные параметры и возвращаемое значение. Очевидно, в слу­чае объявления переменной ее описание будет содержать другую информацию.

В приведенном ниже фрагменте кода показан пример комментария в стиле PHPDoc для простой функции, объявленной пользователем.

<?php /**

*  mySimpleFunction

*         

*  Простая функция, возвращающая приветствие

*  пользователю по его имени и возрасту

*         

*  ©param string $name Имя пользователя

*  @param int       $age Возраст пользователя

*  @return string            Готовое сообщение

*/

function mySimpleFunction($name, $age) {

$str = sprintf(■Hello %s, your age is %d', $name, $age); return $str;

}

Первое, что следует отметить, — это начало блока комментариев. Группа сим­волов /** указывает синтаксическому анализатору PHPDoc на начало блока ком­ментариев в данном формате.

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

Следующий раздел комментария — это более развернутое описание. Здесь надо попытаться описать, что из себя представляет функция, класс или переменная с точки зрения их внешнего употребления, — т.е. не как они устроены, а что кон­кретно делают. Подробным описаниям операций и тонкостей работы место не здесь, а в стандартных комментариях внутри кода.

В последнем разделе блока комментариев содержатся различные параметры формата PHPDoc, используемые синтаксическим анализатором для генерирования качественной и удобной документации к программному интерфейсу. Каждый па­раметр начинается с символа за которым без пробела следует имя параметра.

После него располагается информация, требуемая этим параметром согласно син­таксису.

Примечание

Хотя это и не обязательно, каждую строку в блоке комментариев /** … */ обычно начинают с сим­вола звездочки (*). В основном это делается для улучшения читаемости, а также для того, чтобы сразу ви­деть, где в коде расположены блоки PHPDoc-комментариев,

В приведенном примере имеются параметры @рагаш и @return. Параметр @param описывает аргументы функции: во-первых, тип аргумента (в нашем случае первый аргумент — строка символов); во-вторых, его имя (здесь это $паше); и, на­конец, краткое описание данных, передаваемых через этот аргумент. Параметр ©return описывает, какого рода результат возвращает функция; здесь указывается его тип данных и дается краткое описание сути передаваемой информации.

Более подробную информацию об утилите phpDocumentor можно найти на странице phpDocumentor Guide to Creating Fantastic Documentation («Руководство к phpDocumentor по созданию превосходной документации») по адресу http://www.phpdoc.org/tutorial.php.