PHP/phpdoc.md

PHPDoc

PHPDoc - система документирования PHP кода, основанная на Javadoc. Суть системы заключается в том, что к коду пишутся комментарии специального формата перед теми или иными сущностями (функциями, классами, методами, свойствами и т. д.). В дальнейшем эти комментарии парсятся IDE (для подсказок в автодополнении) или специальными утилитами (PHPDocumentor) для генерации документации по коду.

Синтаксис

Комментарий

/**
 *   
 */

Как видите, это обычный многострочный комментарий, у которого две звездочки в начале комментария, в отличие от обычных комментариев.

Директивы (тэги)

Директива (тэг) - одно поле, которое несет определенную информацию о сущности кода. Начинаются с собаки @. Например

• @param - параметр функции/метода
• @return - тип и описание возвращаемого значения метода/функции.
• @var - тип и описание переменной/свойства объекта

Общие директивы файла

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

@author

Имя автора кода:

/**
 *  @author Name Surname 
 *  @author Name Surname <email@example.com>
 */

@copyright

/**
 *  @copyright 1980-20100500 The Super Team
 */

@license

/**
 *  @license MIT
 *  или
 *  @license https://opensource.org/licenses/MIT  
 */

@package

Обычно применяются для документирования и/или разделения кода на логические элементы. Зачастую совпадает (хотя вовсе не обязательно) с тем или иным namespace

/**
 * @package yii\base\Model
 */

@see

Ссылка на дополнительный материал. Может быть внешней ссылкой или ссылкой на другой блок PHPDoc

/**
 *  @see http://google.com
 *  @see http://php.net
 *  @see ContactForm::rules
 */

@version

Версия. Может быть указана литерально, или же взята из системы контроля версий

/**
 * @version 0.0.1 Pre-alpha
 * @version GIT: $Id$
 */

Для задания версии в git надо поколдовать с git describe

Тэги классов

Ниже показаны тэги, которые относятся к классам

@method

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

/**
 *  @method void reboot()
 *  @method bool shutdown()
 */
class MagicCallableClass {
    function __call($name, $arguments){
        if ($name === 'reboot'){
            echo "рыбут";
        }
        if ($name === 'shutdown'){
            echo "выкл";
            return true;
        }
    }
}

В примере выше нет отдельных методов reboot и shutdown, однако есть логика в __call, которая обеспечивает их работу

@property, @property-read, @property-write

Описания свойств, созданных с помощью __get и __set, аналогично @method

Тэги сущностей классов и объектов

@abstract

Абстрактные методы и свойства

@access

Тип доступа: private, public или protected

@final

ООП final

Функции и методы

PHPDoc указываются непосредственно перед функцией или методом

@param

Самый часто употребляемый тэг:

/**
 *  @param Тип Имя Описание 
 */

/**
 *  @param int $afterSeconds Delay before reboot
 */
function reboot($afterSeconds){

}

@return

Очевидно, тип и описание возвращаемого значения функции

/**
 *  @param float $value Value to calculate square root of it
 *  @return float|null Square root or NAN if $value less than zero
 */

function sqrt($value){
    ...
}

Типы данных

Для указания типов в @param, @return, @global используется следующий синтаксис:

• string
• int или integer
• float
• bool или boolean
• array
• resource
• null
• callable

Более сложные случаи

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

• mixed неизвестный тип, например в функциях, результат которых зависит от типов данных параметров
• void. Обычно применяется для @return, если функция ничего не возвращает;
• object.
• false или true. Обычно используется в функциях, которые возвращают false и какое-то значение в других случаях (которое интерпретируется как true, но это вовсе не обязательно тип bool)
• self - объект того же типа, что и вызыван
• static
• $this - используется для указания на chaining.

Массивы

Обычно указываются с помощью [] после типов/ключевых слов выше:

/**
 * array_map 
 * 
 * @param callable $callback 
 * @param mixed[] $array 
 * @return mixed[]
 */
function array_map($callback, $array){

}

Несколько типов

Объединяются через трубу ('палку', 'или'):

/**
 * @return string|null
 */

@global

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