DocBlock комментарии для документирования PHP кода

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

Комментарий документа начинается с косой черты и двух звездочек /**, заканчивается звездочкой и косой чертой */.

Комментарий в одну строку выглядит так:

/** Однострочный комментарий к документу */

Многострочный комментарий выглядит так:

/**
* Многострочный документ-комментарий
*/

Весь синтаксис строится на использовании дескрипторов и их значений, обернутых в комментарий:

/**
* @имя_дескриптора значение_директивы
* @имя_дескриптора значение_директивы
*/

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

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

1. @var описание для свойств класса, подробнее
2. @return описания данных, возвращаемых функцией или методом, подробнее
3. @param тип и имя параметра передаваемого в функцию, подробнее
4. @deprecated указывает что код устарел, подробнее
5. @package имя пакета в который входит данный программный код, подробнее
6. @author имя автора кода, подробнее
7. @version версия реализации документируемого кода, подробнее
8. @todo будущие возможные изменения кода, подробнее
9. @global список глобальных переменных, которые используются внутри функции,метода, класса, подробнее
10. @ignore используется, когда элемент предназначен только для внутреннего использования и его следует пропустить утелите DocBlock, подробнее

Дескрипторы для PHP

Дескриптор @throws

Синтаксис:

@throws [тип] [<описание>]

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

/**
* @throws InvalidArgumentException если элемент не массив
*/

Дескриптор @global

Синтаксис:

@global [тип] [имя] [<описание>]

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

/**
* @global string $gStr глобальная строчная переменная
*/

Дескриптор @name

Синтаксис:

@name [имя]

Используется в связки с @global, для отождествления.

/**
* @name $globalVarName
*/

Дескриптор @internal

Синтаксис:

@internal [описание]

Значение дискриптора не будет добавлено в файлы документации. Удобно, если нужно оставить комментарий только для тех, кто работает с кодом.

/**
* @internal Этот комментарий не будет добавлен в документацию
*/

Дескриптор @return

Синтаксис:

@return [тип] [<описание>]

Используется для описания данных, возвращаемых функцией или методом класса. Если в качестве типа будет указано имя класса, phpDocumentor автоматически создаст ссылку на данный класс.

/**
* @return integer количество строк
* @return string|null строка после проверки
*/

Дескриптор @ignore

Синтаксис:

@ignore [<описание>]

Сообщает phpDocumentor, что данный код не следует включать в лист документации.

/**
* @ignore
* @ignore описание почему мы игнорируем текущий элемент
*/

Дескриптор @package

Синтаксис:

@package [уровень 1]\[уровень 2]\[и т.д.]

Указание имени пакета, в который входит данный программный код (файл). Используется в заголовочном блоке файла или в блоке комментариев класса.

/**
* @package Yii\Documentation\API
*/

Дескриптор @subpackage

Синтаксис:

@subpackage [имя]

Объеденяет несколько пакетов в один раздел документации. Используется с тегом @package. Применяется в начале файла или заглавном докблоке класса.

/**
* @subpackage Documentation\API
*/

Дескриптор @link

Синтаксис:

@link [url] [<описание>]
@link Больше информации об объекте ({@link https://hmarketing.ru/doc})

Дает возможность добавить ссылку к любому документируемому коду.

/**
* @link https://hmarketing.ru/doc дополнительная документация
*/

Дескриптор @method

Синтаксис:

@method [возвращаемый тип] [название]([[тип] [параметр]<, ...>]) [<описание>]

Аналогичен @property, указывает какие магические методы класса можно вызвать.

/**
* @method string getStr()
* @method setStr(integer $integer)
*/

Дескриптор @param

Синтаксис:

@param [тип] [имя] [<описание>]

Тег описывает входные параметры для функций и методов классов.

/**
* @param integer $value
* @param integer $value описание переменной
*/

Дескрипторы для ООП

Дескриптор @static

Синтаксис:

@static [имя]

Указывает на то, что метод или свойство является статическим.

/**
* @static $value
*/

Дескриптор @abstract

Синтаксис:

@abstract [имя]

Описывает абстрактные классы, методы или свойства.

/**
* @abstract $value
*/

Дескриптор @access

Синтаксис:

@access [private | protected | public]

Описывает доступ к элементу, особой надобности в этом дискрипторе нет, т.к. перед методом (функцией) или свойством (переменной) обычно указывается область видимости.

/**
* @access private 
* @access protected 
* @access public
*/

Дескриптор @final

Синтаксис:

@final

Дескриптор отмечает методы или свойства, которые не могут быть перегружены в дочерних классах. Также может быть отмечен класс, который не должен быть наследован.

/**
* @final
*/

Дескриптор @property

Синтаксис:

@property [< чтение | запись >] [Тип] [имя] [<описание>]

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

/**
* @property string $myProperty
*/

Дескриптор @property-read

Синтаксис:

@property [< чтение | запись >] [Тип] [имя] [<описание>]

Описывает свойство класса, которое может быть только прочитано с помощью магического метода __get(). Используются только в блоке описания класса.

/**
* @property-read string $myProperty
*/

Дескриптор @property-write

Синтаксис:

@property [< чтение | запись >] [Тип] [имя] [<описание>]

Описывает свойство класса, которое может быть только записано с помощью магического метода __set(). Используются только в блоке описания класса

/**
* @property-write string $myProperty
*/

Дескриптор @var

Синтаксис:

@var [тип] [имя] [<описание>]

Указывает описание для свойств класса.

/**
* @var string $value строка с данными
*/

Дескрипторы для общей информации

Дескриптор @todo

Синтаксис:

@todo [описание]

Описывает необходимые доработки кода.

/**
* @todo исключить возможность вызова без авторизации
*/

Дескриптор @author

Синтаксис:

@author [имя автора] [<email адрес>]

Имя автора кода, phpDocumentor будет искать текст между угловыми скобками < >. Если такая конструкция будет найдена и ее формат будет соответствовать e-mail адресу, то она будет преобразована в соответствующую ссылку.

/**
* @author Hmarketing
* @author Hmarketing <info@hmarketing.ru>
*/

Дескриптор @copyright

Синтаксис:

@copyright [описание]

Информация, указывающая на правообладателя кода.

/**
* @copyright 2010-2024 The hmarketing.ru
*/

Дескриптор @license

Синтаксис:

@license [<url>] [название]

Ссылка на лицензию, под которой распространяется код.

/**
* @link https://hmarketing.ru/license.txt GNU Public License
* @link GPL
*/

Дескриптор @see

Синтаксис:

@see [url | метод | переменная] [<описание>]

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

/**
* @see https://hmarketing.ru/doc Подробная документация
* @see MyClass::$val
* @see MyClass::myFunction()
*/

Дескриптор @since

Синтаксис:

@since [версия] [<описание>]

Указывает на версию класса, метода или функции с которой комментируемый элемент стал доступен.

/**
* @since 1.0.2 Добавлен аргумент $b
* @since 1.0.1 Добавлен аргумент $a
* @since 1.0.0
*/

Дескриптор @version

Синтаксис:

@version [<вектор>] [<описание>]

Текущая версия реализации документируемого кода.

/**
* @version 1.1
* @version v 1.1  дата релиза 2024-04-29;
*/

Дескрипторы для объединения

Дескриптор @uses

Синтаксис:

@uses [метод|переменная] [<опимание>]

Описывает связь между текущем элементом и другим структурным элементом.

/**
* @uses MyClass::$items для получения счетчика
*/

Дескриптор @category

Синтаксис:

@category [описание]

Имя категории, в которую объединены несколько пакетов.

/**
* @category MyCategory
*/

Дескрипторы для метки устаревшего кода

Дескриптор @deprecated

Синтаксис:

@deprecated [<версия>] [<описание>]

Дескриптор указывает на то, что код устарел. В качестве значения дескриптора указывается версия, начиная с которой код считается устаревшим.

/**
* @deprecated
* @deprecated 1.0.0
* @deprecated Использует небезопасные методы
* @deprecated 1.0.0 Использует небезопасные методы
*/

Дескрипторы для подключения сторонних файлов

Дескриптор @example

Синтаксис:

@example [путь] [<стартовая линия> [<количество строк>] ] [<описание>]

Путь к файлу с примером использования кода. Стартовая линия - номер строки, с которой нужно отобразить пример (не обязательно). Количество строк - количество строк для представления примера от стартовой линии. Если не указано, файл примера будет показан ​​от линии старта до конца файла (не обязательно). Если нет стартовой линии, то файл примера будет представлен полностью.

/**  
* @example myExample.php Пример выполнения метода
* @example http://example.com/myExample.php Пример выполнения метода при условии, что старт == 1
* @example "My Own Example.php" My counting
*/

Дескриптор @filesource

Синтаксис:

@filesource

Тег может быть использован только в начале файла. Указывает, что необходимо вывести исходный код текущего файла.

/**
* @filesource
*/

Дескрипторы для работы с API

Дескриптор @api

Синтаксис:

@api

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

/**
* @api
*/