Что такое PHPDoc?

Это стандарт документирования исходного кода. На текущий момент стандарт имеет формальный статус, но планируется его принятие группой PHP-FIG под названием PSR-5.

Зачем это нужно?

- При разработке больших проектов в команде разработчикам проще разобраться в существующем коде, читая комментарии, оставленные авторами исходного кода.
- При разработке своих проектов приходится разбираться с кодом, написанным очень давно. В этом случае ознакомление с собственными комментариями позволяет быстро разобраться в ранее написанном функционале.
- Во многих IDE имеется механизм автодополнения кода, когда, например, при написании метода показывается подсказка, относящаяся к данному методу.
- С помощью отдельных программ, например phpDocumentor можно сформировать документацию из исходного кода с Doc-блоками.

Пример (взят из исходного кода Yii 2 и приведен с небольшими сокращениями)

/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yiiase;

use Yii;

/**
 * Action is the base class for all controller action classes.
 *
 *
 * @author Qiang Xue 
 * @since 2.0
 */
class Action extends Component
{
    /**
     * @var string ID of the action
     */
    public $id;
    /**
     * @var Controller|yiiwebController the controller that owns this action
     */
    public $controller;


    /**
     * Constructor.
     *
     * @param string $id the ID of this action
     * @param Controller $controller the controller that owns this action
     * @param array $config name-value pairs that will be used to initialize the object properties
     */
    public function __construct($id, $controller, $config = [])
    {
        $this->id = $id;
        $this->controller = $controller;
        parent::__construct($config);
    }

    /**
     * Returns the unique ID of this action among the whole application.
     *
     * @return string the unique ID of this action among the whole application.
     */
    public function getUniqueId()
    {
        return $this->controller->getUniqueId() . '/' . $this->id;
    }

    /**
     * Runs this action with the specified parameters.
     * This method is mainly invoked by the controller.
     *
     * @param array $params the parameters to be bound to the action's run() method.
     * @return mixed the result of the action
     * @throws InvalidConfigException if the action class does not have a run() method
     */
    public function runWithParams($params)
    {
        if (!method_exists($this, 'run')) {
            throw new InvalidConfigException(get_class($this) . ' must define a "run()" method.');
        }
        $args = $this->controller->bindActionParams($this, $params);
        Yii::trace('Running action: ' . get_class($this) . '::run()', __METHOD__);
        if (Yii::$app->requestedParams === null) {
            Yii::$app->requestedParams = $args;
        }
        if ($this->beforeRun()) {
            $result = call_user_func_array([$this, 'run'], $args);
            $this->afterRun();

            return $result;
        } else {
            return null;
        }
    }

    /**
     * This method is called right before `run()` is executed.
     * You may override this method to do preparation work for the action run.
     * If the method returns false, it will cancel the action.
     *
     * @return bool whether to run the action.
     */
    protected function beforeRun()
    {
        return true;
    }

    /**
     * This method is called right after `run()` is executed.
     * You may override this method to do post-processing work for the action run.
     */
    protected function afterRun()
    {
    }
}

 

Синтаксис

Любые многострочные или однострочные комментарии по стандарту PHPDoc должны начинаться с /** и заканчиваться */.

Список используемых тэгов: @api, @author, @copyright, @deprecated, @example, @global, @internal, @license, @method, @package, @param, @property, @return, @see, @since, @throws, @todo, @uses, @var, @version.

Все другие тэги (@link, @subpackage, @category, @abstract, @final, @access) на данный момент признаны устаревшими и не рекомендованы к использованию.

Подробнее о применении тэгов с примерами:

- @api
Применяется, если элемент является частью структуры API для использования во внешних программных продуктах.

/**
 * @api
 */
function getCount()
{

}

- @author
Применяется для указания автора программного кода.

/**
 * @author Ivan Ivanov
 */
class A
{

}

- @copyright
Применяется для указания правообладателя программного продукта.

/**
 * @copyright Copyright (c) 2001-2017 My Company Inc.
 */
class A
{

}

- @deprecated
Применяется для информирования об устаревшем коде. Можно указать версию, начиная с которой код является устаревшим.

/**
 * @deprecated
 */
class A
{

}

/**
 * @deprecated 1.0.1
 */
class B
{

}

- @example
Применяется для указания пути к файлу, содержащему пример работы, использования и т.п.

/**
 * @example http://abc.com/example.php
 */
class A
{

}

- @global
Применяется для информирования об использовании глобальных переменных.

/**
 * @global  resource  $db
 */
function getActiveItems()
{
    global $db;
}

- @internal
Информирует, что данный класс, метод класса или функция используется исключительно для внутренней работы этой части ПО. Игнорируется PhpDocumentor при составлении документации.

/**
 * @internal
 *
 * @return array
 */
function getElements()
{

}

- @license
Применяется для указания лицензии программного продукта.

/**
 * @license GPL
 */
class A
{

}

/**
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */
class B
{

}

- @method
Используется, когда класс содержит "магический" метод __call() и определяет использование данного метода.

/**
 * @method string getString()
 * @method void setString(int $integer)
 */
class A
{
    public function __call($name, $arguments) 
    {

    }
}

- @package
Используется в качестве аналога или дополнения к пространству имен.

/**
 * @package SystemWeb
 */
class A
{

}

- @param
Используется для описания входных параметров для метода класса или функции.

/**
 * @param int   $count    Count of items
 */
function setCount($count)
{

}

class A
{
    /**
     * @param int   $count    Count of items
     */
    public function setCount($count)
    {

    }
}

- @property
Используется, когда класс содержит "магические" методы __get() или __set() и определяет использование данных методов.

/**
 * @property int $count
 */
class A
{
    public function __get($name)
    {

    }
}

- @return
Применяется для указания данных, возвращаемых методом класса или функцией.

class A
{
    /**
     * @return integer  Count of items
     */
    public function getCount()
    {

    }
}

- @see
Применяется для указания ссылки на другие комментарии в формате DocBlock или на определенный URI.

/**
 * @see http://abc.com/docs/
 */
 public function bar()
 {

 }

 class A
 {
    /**
     * @see CacheClass::set()
     */
    public function checkCashe()
    {

    }
 }

- @since
Применяется для указания версии, начиная с которой доступен данный функционал.

/**
 * @since 1.0.4
 */
class A
{

}

- @throws
Применяется для указания возвращаемых типов исключений.

/**
 * @throws   NotFoundException
 */
function baz()
{

}

- @todo
Применяется для указания планов по дальнейшей разработке.

/**
 * @todo Add second parameter with extended information
 *
 * @param  int   $id   Item ID
 * @return void
 */
function foo($id)
{

}

- @uses
Применяется для указания стороннего функционала из других классов или функций, который используется в данном методе класса или функции.

/**
 * @uses AbcClass::getCount() to retrieve the count of items
 */
function bar()
{
    $count = AbcClass::getCount();

}

- @var
Применяется для указания свойства класса.

class A
{
    /**
     * @var int   Count of items
     */
    public $count = 0;
}

- @version
Применяется для указания текущей версии.

/**
 * @version 1.0.1
 */
class A
{

}

Источники:

https://ru.wikipedia.org/wiki/PHPDoc
https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md