# PHPDoc

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

## Синтаксис

### Комментарий

```php
/**
 *   
 */
```

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

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

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

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

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

#### `@author`

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

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

#### `@copyright`

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

#### `@license`

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

#### `@package`

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

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

#### `@see`

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

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

#### `@version`

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

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

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

### Тэги классов

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

#### `@method`

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

```php

/**
 *  @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`

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

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

```

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

}
```

#### `@return`

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

```php
/**
 *  @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){
    ...
}
```