PHP
PHPDoc

Синтаксис

• @api
• @author [имя] [<адрес электронной почты]]
• @copyright <описание>
• @deprecated [<"Семантическая версия">] [: <"Семантическая версия">] [<description>]
• @example [URI] [<описание>]
• {@example [URI] [: <старт> .. <конец>]}
• @inheritDoc
• @internal
• {@internal [description]}}
• @license [<Идентификатор SPDX> | URI] [имя]
• @method [return "Type"] [name] (["Type"] [parameter], [...]) [description]
• @package [уровень 1] \ [уровень 2] \ [и т. д.]
• @param ["Тип"] [имя] [<описание>]
• @property ["Тип"] [имя] [<описание>]
• @return <"Тип"> [описание]
• @see [URI | "FQSEN"] [<description>]
• @since [<"Семантическая версия">] [<description>]
• @throws ["Type"] [<description>]
• @todo [описание]
• @uses [файл | "FQSEN"] [<description>]
• @var ["Type"] [element_name] [<description>]
• @version ["Семантическая версия"] [<description>]
• @filesource - включает текущий файл в результаты анализа phpDocumentor
• @link [URI] [<description>] - тег Link помогает определить отношение или ссылку между структурными элементами .

замечания

/**
 *
 */

Добавление метаданных к функциям

Аннотации уровня функции помогают IDE идентифицировать возвращаемые значения или потенциально опасный код

/**
 * Adds two numbers together.
 *
 * @param Int $a First parameter to add
 * @param Int $b Second parameter to add
 * @return Int
 */
function sum($a, $b)
{
    return (int) $a + $b;
}

/**
 * Don't run me! I will always raise an exception.
 *
 * @throws Exception Always
 */
function dangerousCode()
{
    throw new Exception('Ouch, that was dangerous!');
}

/**
 * Old structures should be deprecated so people know not to use them.
 *
 * @deprecated
 */
function oldCode()
{
    mysql_connect(/* ... */);
}

Добавление метаданных в файлы

Метаданные уровня файла применяются ко всему коду внутри файла и должны быть размещены в верхней части файла:

<?php

/**
 * @author John Doe ([email protected])
 * @copyright MIT
 */

Наследование метаданных из родительских структур

Если класс расширяет другой класс и будет использовать одни и те же метаданные, предоставляя ему @inheritDoc простой способ использования одной и той же документации. Если несколько классов наследуются от базы, для детей, которые будут затронуты, необходимо изменить только базу.

abstract class FooBase
{
    /**
     * @param Int $a First parameter to add
     * @param Int $b Second parameter to add
     * @return Int
     */
    public function sum($a, $b) {}
}

class ConcreteFoo extends FooBase
{
    /**
     * @inheritDoc
     */
    public function sum($a, $b)
    {
        return $a + $b;
    }
}

Описание переменной

@var слово @var можно использовать для описания типа и использования:

• свойство класса
• локальная или глобальная переменная
• класс или глобальная константа

class Example {
    /** @var string This is something that stays the same */
    const UNCHANGING = "Untouchable";

    /** @var string $some_str This is some string */
    public $some_str;

    /**
     * @var array $stuff    This is a collection of stuff
     * @var array $nonsense These are nonsense
     */
    private $stuff, $nonsense;

    ...
}

Тип может быть одним из встроенных типов PHP или определяемым пользователем классом, включая пространства имен.

Имя переменной должно быть включено, но может быть опущено, если docblock применяется только к одному элементу.

Описание параметров

 /**
 * Parameters
 * 
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param($int, $string, $array, $bool)
{
}

 /**
 * Parameters - Optional / Defaults
 *
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false)
{
}

/**
 * Parameters - Arrays
 * 
 * @param array          $mixed
 * @param int[]          $integers
 * @param string[]       $strings
 * @param bool[]         $bools
 * @param string[]|int[] $strings_or_integers
 */
function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers)
{
}

/**
 * Parameters - Complex
 * @param array $config 
 * <pre>
 * $params = [
 *         'hostname'     => (string) DB hostname. Required.
 *         'database'     => (string) DB name. Required.
 *         'username'     => (string) DB username. Required.
 * ]
 * </pre>
 */
function demo_param_complex($config)
{
}

Коллекции

PSR-5 предлагает форму новаций в стиле Generics для коллекций.

Синтаксис Generics

Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>

Значения в коллекции МОГУТ даже быть еще одним массивом и даже другой коллекцией.

Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>

Примеры

<?php

/** 
 * @var ArrayObject<string> $name 
 */
$name = new ArrayObject(['a', 'b']);

/** 
 * @var ArrayObject<int> $name 
 */
$name = new ArrayObject([1, 2]);

/** 
 * @var ArrayObject<stdClass> $name 
 */
$name = new ArrayObject([
    new stdClass(), 
    new stdClass()
]);

/** 
 * @var ArrayObject<string|int|stdClass|bool> $name 
 */
$name = new ArrayObject([
    'a', 
    true, 
    1, 
    'b', 
    new stdClass(), 
    'c', 
    2
]);

/**
 * @var ArrayObject<ArrayObject<int>> $name 
 */
$name = new ArrayObject([
    new ArrayObject([1, 2]), 
    new ArrayObject([1, 2])
]);

/** 
 * @var ArrayObject<int, string> $name 
 */
$name = new ArrayObject([
    1 => 'a', 
    2 => 'b'
]);

/** 
 * @var ArrayObject<string, int> $name 
 */
$name = new ArrayObject([
    'a' => 1, 
    'b' => 2
]);

/** 
 * @var ArrayObject<string, stdClass> $name 
 */
$name = new ArrayObject([
    'a' => new stdClass(), 
    'b' => new stdClass()
]);