Документирование php скриптов с помощью phpDoc и phpDocumentor

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

@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() {
    }

.
Прокомментировать/Отблагодарить