Документирование классов с помощью PHPDoc

Задача
Необходимо иметь возможность интегрировать документацию с программой.

Решение
Для этого предназначен PHPDoc, позволяющий PEAR составить точный перечень ваших классов; таким образом, инструментарий PHPDoc можно применять для автоматической генерации API-документации, написанной на HTML и XML.

Синтаксис PHPDoc основан на Javadoc. Допустимо применение следующих тегов: @access, @author, @package, @param, @return, @since, @var и @version.

Теперь утилиту PEAR PHPDoc можно применять для создания документации.

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

Комментарии PHPDoc основаны на тех же самых соглашениях о способах форматирования и именования, что приняты в Javadoc. Поэтому блок комментариев, предназначенный для обработки PHPDoc, обозначатся посредством традиционного комментария, принятого в C, но только за открывающей косой чертой должны располагаться две звездочки:

/**
* Это блок комментариев PHPDoc
*/

Внутри такого блока определенные ключевые слова приобретают дополнительное специальное значение.


Все эти ключевые слова начинаются с символа «@», или с «собаки».

Наиболее полный пример выглядит так:

/**
* Example_Class – это простой класс для демонстрации PHPDoc
*
* Example_Class не содержит полезного кода, а служит
* для наглядной демонстрации того, как применяются
* и используются различные служебные конструкции PHPDoc.
*
* Пример применения:
* if (Example_Class::example()) {
* print "I am an example.";
* }
*
* @package Example
* @author David Sklar
* @author Adam Trachtenberg
* @version $Revision: 1.30 $
* @access public
* @see http://www.example.com/pear
*/
class Example extends PEAR
{
/**
* returns the sample data
*
* @param string $sample the sample data
* @return array all of the exciting sample options
* @access private
*/
function _sampleMe($sample)
{

Любой текст, следующий за ключевым словом, трактуется как значение, присвоенное этому слову. Поэтому в данном примере значением @package является «Example».


В зависимости от ситуации допускается наличие более одного экземпляра для ключевого слова. Например, вполне законно иметь несколько ключевых слов @param, но наличие нескольких слов @return недопустимо.

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

Чтобы собрать PHPDoc и потом работать с ней, сначала надо установить пакет PEAR PHPDoc. Внутри этого пакета находится программа phpdoc. Запустите ее из командной строки с флагом -s для передачи каталога исходных файлов. По умолчанию документация создается в каталоге /usr/local/doc/pear/, поэтому убедитесь, что программа phpdoc имеет право записи в этот каталог, или измените место назначения с помощью аргумента -d.
Чтобы окончательно изменить значения, принятые по умолчанию, отредактируйте значения в начале сценария. Вызов с параметром -h выдаст список всех возможных параметров командной строки.

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

Оцените статью: (0 голосов)
0 5 0

Статьи из раздела PHP на эту тему:
Нахождение пакетов PEAR
Обновление пакетов PEAR
Поиск информации о пакете
Работа с менеджером пакетов PEAR
Удаление пакетов PEAR

Вернуться в раздел: PHP / 21. PEAR