# 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 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`.

#### Массивы

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

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

}
```

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

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

```php
/**
 * @return string|null
 */
```

### `@global`

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