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 double $value Value to calculate square root of it
 *  @return double|NAN Square root or NAN if $value less than zero
 */

function sqrt($value){
    ...
}