phpDocumentor - это инструмент для автоматической генерации документации из PHP-кода на основе специальных комментариев.
phpDoc - это стандарт написания этих комментариев.
Проще говоря:
phpDoc поддерживается:
DocBlocks
DocBlock - это специальный многострочный комментарий, который начинается с /** и используется для описания:
- Пример DocBlock
/**
* Class for working with users
*
* Handles user registration, authentication,
* and user profile management.
*
* @author Orkhan
* @package App\Models
*/
class User
{
}
- Из чего состоит DocBlock
DocBlock логически состоит из трёх частей:
Summary (Краткое описание)
Первая строка комментария - короткое описание, обычно одно предложение.
/** * Returns a user by ID */
Рекомендации:
Description (Подробное описание)
Многострочное описание, идущее после summary.
/** * Returns a user by ID * * The method queries the database * and throws an exception if the * user is not found. */
Используется для:
Tags & Annotations
Теги начинаются с @ и содержат структурированную информацию.
/** * @param int $id User identifier * @return User|null * @throws UserNotFoundException */
Справочник phpDoc
@api
Помечает структурный элемент, используемый сторонними программами, и являющийся частью API.
/**
* This method displays the release version
*
* @api
* @return void
*/
function showVersion() {}
@author
Задает имя автора.
/** * @author My Name * @author My Name <my.name@example.com> */
@category
Использовался в старых проектах, сейчас не рекомендуется.
@copyright
Информация об авторских правах.
/** * @copyright 2018 Company Name */
@deprecated
Тег для пометки элементов на удаление в будущих версиях.
/** * @deprecated * @deprecated 1.0.0 * @deprecated No longer used within the code and not recommended */
@example
Пример использования.
/** * @example * $user = $service->getUser(1); */
@filesource
Показывает исходный код файла в документации.
/** * @filesource */
@global
Описание глобальной переменной.
/** * @global PDO $db */
@ignore
Сообщает в phpDocumentor, что следующий структурный элемент обрабатывать не надо.
/** * @ignore */
@internal
Для внутреннего использования, не для публичного API.
/**
* @internal
* @return int Returns an integer value - the count of something
*/
function count() {}
@license
Лицензия проекта.
/** * @license GPL * @license http://opensource.org/licenses/gpl-license.php GNU Public License */
@link
Связывает структурный элемент с сайтом, откуда он взят.
/**
* @link http://example.com Function documentation
* @return int Returns an integer value - the count of something
*/
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
Логическая группировка классов.
/** * @package App\Services */
@param
Описание параметра функции или метода.
/**
* Counts the number of items in the provided array
*
* @param mixed[] $items Array of values
* @param int|string $value Some value
* @return int Returns the index of the element
*/
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 Function documentation
* @see MyClass::$items Element properties
* @see MyClass::setItems() Sets the elements of the collection
* @return int Shows the number of elements in the collection
*/
function count() {}
@since
Версия, с которой доступен элемент.
/**
* Project file
*
* @package test
* @version 1.5.2
*/
/**
* The dataFunction function
*
* @since Version 1.1.2
*/
function dataFunction() {}
@source
Показывает фрагмент исходного кода.
/** * @source */
@subpackage
Подпакет внутри @package.
/** * @subpackage Auth */
@throws
Описывает выбрасываемые исключения.
/** * @throws Exception */
@todo
Заметка о будущем улучшении.
/** * @todo Add caching */
@uses
Показывает использование метода или класса.
/** * @uses Logger::log() */
@var
Тип переменной или свойства.
/** * @var string */ private $name;
@version
Версия элемента.
/** * @version 2.0 */
Генерация документации с помощью phpDocumentor
- Установка phpDocumentor:
composer require --dev phpdocumentor/phpdocumentor
- Базовая генерация документации:
vendor/bin/phpdoc -d src -t docs
Где:
- Использование конфигурационного файла:
Создаём phpdoc.xml:
<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor>
<paths>
<directory>src</directory>
</paths>
<settings>
<visibility>public,protected</visibility>
</settings>
</phpdocumentor>
Запуск:
vendor/bin/phpdoc
- Результат
phpDocumentor генерирует:
Документация удобно размещается:
Source: Orkhan Alishov's notes