Если вы когда-нибудь пытались прочитать код, написанный кем-то, кроме вас, вы знаете, что это может быть сложной задачей. Беспорядочный "код спагетти", смешанный с множеством странно названных переменных, заставляет вашу голову кружиться. Эта функция ожидает строку или массив? Эта переменная хранит целое число или объект? После бесчисленных часов следования за нитями кода и попытки понять, что делает каждый бит, нередко отказаться и просто переписать все с нуля - задача, которая тратит слишком много вашего драгоценного времени.

PHPDoc, сокращение от PHPDocumentor, является мощным инструментом, который позволяет легко документировать ваш код с помощью специально отформатированных комментариев. Документация будет доступна не только в исходном коде, но и в профессиональной документации, извлеченной с использованием веб-интерфейса или интерфейса командной строки. Результат может быть в различных форматах, таких как HTML, PDF и CHM. Кроме того, многие IDE, которые обеспечивают завершение кода, могут анализировать комментарии PHPDoc и предоставлять полезные функции, такие как подсказки типов. Используя PHPDoc, вы можете позволить другим (и вам самим) легко понять ваш код - через недели, месяцы и даже годы после его написания.

DocBlocks

DocBlock - это многострочный комментарий в стиле C, используемый для документирования блока кода. Он начинается с /** и имеет звездочку в начале каждой строки.

/**
 * <...>
 */

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

/**
 * Этот класс является примером использования doc-блоков phpDoc
 */
class SomeClass
{
    /** @type string|null Текст приветствия */
    protected $weclome = null;
    
    /**
     * Этот метод задает текст приветствия.
     * @param string $text текст приветствия, максимум 255 символов.
     * @return void
     */
    public function setWeclomeText($text)
    {
        $this->weclome = $text;
    }
}

DocBlocks состоит из трех разделов: краткое описание, длинное описание и теги. Все три раздела являются необязательными.

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

Длинное описание - это то, куда уходит основная часть документации; это может быть многострочно и сколько угодно времени.

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

Раздел тегов DocBlock содержит любое количество специальных тегов, обозначаемых символом @. Теги используются для указания дополнительной информации, такой как ожидаемые параметры и их тип. Большинство тегов должны быть в отдельной строке, за исключением определенных тегов, которые могут быть встроенными. Встроенные теги окружены фигурными скобками и могут быть как в длинном, так и в коротком описании.

Не все элементы кода могут быть документированы с помощью DocBlocks. Вот список элементов кода, которые могут быть документированы:

  • файлы
  • Классы
  • Функции и методы
  • Свойства класса
  • Глобальные переменные
  • include() / require()
  • define()

Справочник phpDoc

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

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

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

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

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

/**
 * @copyright 2020-2021 The alishoff.com
 */

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

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

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

/**
 * @filesource
 */

@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://example.com Документация к функции.
 * @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 {}

@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://example.com Документация функции.
 * @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() {}

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

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

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

/**
 * Пример использования тега @version
 * @version v 1.2
 */
function dataFunction() {}

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

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

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

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

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

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