Сайт справки

phpDoc и phpDocumentor

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

Генератор phpDocumentor представляет собой отдельную PHP библиотеку доступную в наборе PEAR.

Чтобы получить возможность генерировать, на основе phpDoc комментариев, документацию проекта, нам необходимо скачать и установить набор библиотек PEAR.

Как пользоваться PHPdoc

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

Комментируя код проекта нужно придерживаться определенных правил форматирования комментариев и помещать их в так называемые Doc-блоки.

Doc-блоки скрипта должны быть выделены таким образом:

Одной строкой:

/** <...> */

Либо несколькими строками:

/**
  * <...>
  */

Пример Doc-блока:

/**
  * Этот класс является примером использования doc-блоков phpDoc
  */
 class SomeClass
 {
     /** @type string|null Текст приветствия */
     protected $weclome = null;

     /**
      * Этот метод задает текст приветствия.
      *
      * @param string $text текст приветствия, максимум 255 символов.
      *
      * @return void
      */
     public function setWeclomeText($text)
     {        
         $this->weclome = $text;
     }
 }

Справочник по параметрам блоков, будет приведен ниже.

Снабдив код обильными phpDoc комментариями, мы можем успешно воспользоваться PEAR библиотекой – phpDocumentor, получив готовый справочник-документацию по всем файлам проекта.

Как сгенерировать документацию через phpDocumentor

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

В статье "как установить PEAR" приведен пример, установки библиотеки phpDocumentor, результатом, которого должна создаться директория C:\WebServers\usr\local\php5\data\PhpDocumentor, заполненная файлами генератора, в своей совокупности, представляющих web систему.

В соответствии с инструкцией, используя набор программ денвера, создайте новую директорию C:\WebServers\home\phpdocumentor.ru\www и скопируйте в туда файлы генератора документаций из
C:\WebServers\usr\local\php5\data\PhpDocumentor.

Внимание! Эти действия нужно самостоятельно интерпретировать под ваш WAMP (Windows, Apache, MySQL, PHP), если денвер не используется.

После того как вы настроили новый виртуальный хост для тестирования генератора phpDocumentor, вам станет доступен веб-интерфейс генерации справочника, по адресу phpdocumentor.ru.

Когда вы оформите свой проект phpDoc блоками, запустите веб интерфейс phpdocumentor.ru и перейдите во вкладку "OutPut".

внешний вид phpDoc справочника

В первом поле "Target" укажите путь к директории, в которой будет создана документация. Затем перейдите во вкладку "Files".

Настройка выгрузки проекта в phpDoc

В поле "Directory to parse" задайте путь к корню вашего проекта.

Жмите кнопку "Create" в правом нижнем углу страницы, и ждите, пока завершится процесс создания мануала.
Перейдя в папку указанную во вкладке "OutPut", вы увидите множество файлов и папок, все они представляют документацию к заданному проекту. Прочесть документацию можно открыв файл index.html.

При моих настройках я получил справочник такого вида.

результат генерации phpDoc справочника

Кроме документации в виде набора html файлов, также phpDocumentor позволяет создавать мануалы в PDF, CHM, XML форматах.

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

Справочник phpDoc

@api – помечает структурный элемент, используемый сторонними программами, и являющийся частью API.

/**
  * Этот метод показывает версию релиза
  *
  * @api
  *
  * @return void
  */
  function showVersion()
  {
     <...>
  }

@author – задает имя автора.

/**
  * @author My Name
  * @author My Name <my.name@example.com>;
  */

@copyright – копирайтинг.

/**
  * @copyright 2011-2012 The lifeexample.ru
  */

@deprecated – тег для пометки элементов на удаление в будущих версиях.

/**
  * @deprecated
  * @deprecated 1.0.0
  * @deprecated Больше не используется внутри кода, и не рекомендуется.
  */

@example – пример использования метода или класса.

@filesource – сообщает в phpDocumentor, что нужно включить исходный код в текущий файл для разбора.

/**
  * @filesource
  */

@global – описывает глобальные переменные.

@ignore – сообщает в phpDocumentor, что следующий структурный элемент обрабатывать не надо.

if ($ostest) {
     /**
      * Константа определяет версию операционной системы
      */
     define("OS","Unix");
 } else {
     /**
      * @ignore
      */
     define("OS","Windows");
 }

@internal – говорит, что элемент является внутренним элементом этого приложения или библиотеки.

/**
  * @internal
  *
  * @return Возвращает целочисленное значение - количество чего либо.
  */
 function count()
 {
     <...>
 }

@license – описывает соответствие лицензии.

/**
  * @license GPL
  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  */

@link – связывает структурный элемент с сайтом, откуда он взят.

/**
  * @link http://lifeexample.ru/razrabotka-i-optimizacia-saita/phpdoc-i-phpdocumentor Документация к функции.
  *
  * @return Возвращает целочисленное значение - количество чего либо.
  */
 function count()
 {
     <...>
 }

@method – указывает какие магические (не явные) методы класса можно вызвать.

class Parent
 {
     public function __call()
     {
         <...>
     }
 }

 /**
  * @method string getString()
  * @method void setInteger(integer $integer)
  * @method setString(integer $integer)
  */
 class Child extends Parent
 {
     <...>
 }

@package – классификация структурных элементов в логических подразделениях.

@param – описывает тип и имя параметра передаваемого в функцию.

/**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $array Array массив значений.
  * @param int|string $value некоторое значение.
  * @return int возвращает номер элемента.
  */
 function count(array $items, $value)
 {
     <...>
 }

@property – аналогичен тегу @method. Позволяет классу знать какие можно использовать магические свойства.

class Parent
 {
     public function __get()
     {
         <...>
     }
 }

 /**
  * @property string $myProperty
  */

 class Child extends Parent
 {
     <...>
 }

@property-read – указывает какие можно использовать магические свойства, только для чтения.

class Parent
 {
     public function __get()
     {
         <...>
     }
 }

 /**
  * @property-read string $myProperty
  */
 class Child extends Parent
 {
     <...>
 }

@property-write – указывает какие можно использовать магические свойства, только для записи.

class Parent
 {
     public function __set()
     {
         <...>
     }
 }

 /**
  * @property-write string $myProperty
  */
 class Child extends Parent
 {
     <...>
 }

@return – описывает возвращаемое значение функцией или методом.

/**
  * @return string|null Метка для текста.
  */
 function getLabel()
 {
     <...>
 }

@see – задает ссылку из структурного элемента, на веб-сайт или другой элемент.

/**
  * @see http://lifeexample.ru/foo Документация функции.
  * @see MyClass::$items           свойства элементов.
  * @see MyClass::setItems()       установка элементов коллекции.
  *
  * @return integer Показывает количество элементов в коллекции.
  */
 function count()
 {
     <...>
 }

@since – говорит о том, что структурный элемент стал доступен с заданной версии пакета.

/**
 * Файл проекта
 * @package test
 * @version 1.5.2
 */
/**
 * функция datafunction
 * @since Version 1.1.2
 */
function datafunction()
{
...
}

@subpackage – описывает под-пакет основного пакета, используется вместе с тегом @package.

@todo – документирует задачи, которые необходимо выполнить в ближайшем будущем.

@uses – показывает ссылку на документацию по этому элементу, и создает обратную ссылку в других документациях элементов на него.

@var – указывает описание для свойств класса.

   class class1{
       /**
        * пример документирования переменной
        * @var string
        */
       var $variable;
       /**
        * пример документирования переменной с описанием
        * @var string содержит информацию о  class1
        */
       var $variable_with_desc;
     
    }

@version – версия документа.

/**
     * Пример использования тега @version
     * @version v 1.2  дата релиза 2006-04-29;
     */
    function datafunction() {
    }

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

  • @author;
  • @deprecated;
  • @var;
  • @version;
  • @todo;
  • @return;
  • @package;
  • @param.

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

Поддержка UTF-8 в phpDocumentor

Все здорово, но данное чудо генерации документаций не поддерживает кодировку UTF-8 а следовательно кириллица будет отображаться кракозябрами.

Чтобы подружить phpDocumentor с UTF-8, скачиваем следующий архив

Скачать phpDocumentor с поддержкой UTF-8 

Теперь распакуем скачанный архив в директорию с PEAR: c:\WebServers\usr\local\php5\PEAR\, заменив при этом имеющуюся в ней папку PhpDocumentor.

Если phpDocumentor поднимается на linux, то распакуем скачанный архив в директорию с PEAR: /usr/share/php/PhpDocumentor/, заменив при этом имеющуюся в ней папку PhpDocumentor.

Следующим шагом закомментируем в файле c:\WebServers\usr\local\php5\data\­PhpDocumentor\docbuilder\includes\utilities.php все, что встречается до функции showImage().

После данных действий можно генерировать документацию с поддержкой кириллицы и кодировки UTF-8.

Русификатор шаблона phpDocumentor

Кстати, если хотите поправить верстку шаблона, или русифицировать его, то сделать это можно в директории: c:\WebServers\usr\local\php5\PEAR\PhpDocumentor\phpDocumentor\Converters\­HTML\frames\templates\DOM\earthli\templates\ (это пример директории к шаблону DOM::earthli)

Скачать русифицированный шаблон для phpDocumentor 

Спасибо за внимание, надеюсь информация будет вам полезна!

Наверх

© Сайт справки 2024