Пример подсказок на основе DocBlock комментариев:

Пример подсказки в IDE на основе DocBlock комментариев

DocBlock - это многострочный комментарий переведенный к определенному виду (синтаксису). На основании этих комментариев можно автоматически генерировать документацию с помощью утилиты phpDocumentor. Пример генерируемой документации можно посмотреть на официальном сайте phpDocumentor.

И так разберем подробнее как использовать эти "чудо" комментарии.

Пример использования DocBlock комментариев

Простой пример комментария:

<?php

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* 
* @имя_тега значение
* @return тип_данных
*/

Комментарий должен находиться перед документируемым элементом (классом, функцией, переменной, константой).

Строка комментария должна начинаться с *. Блоки разделяются пустыми строками. Остальные комментарии не подходящий под данный синтаксис будут игнорироваться. Теги также могут находиться в описании объекта, такие теги заключаются в {} скобки и называются инлайн (inline) теги.

Пример с использованием инлайн тегов:

<?php

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* Здесь мы будеи использовать инлайн {@inlinetag} тег
* 
* @имя_тега значение
* @return тип_данных
*/

Общий пример:

<?php

/**
 * Краткое описание класса
 * 
 * Подробное описание класса
 * которое может растянуться на несколько строк с использованием HTML тегов.
 * Теги можно использовать следующие:
 * <b> — жирное начертание;
 * <code> — код;
 * <br> — разрыв строки;
 * <i> — курсив;
 * <kbd> — сочетание клавиш;
 * <li> — элемент списка;
 * <ol> — нумерованный список;
 * <p> — абзац;
 * <pre> — форматированный текст;
 * <samp> — пример;
 * <ul> — маркированный список;
 * <var> — имя переменной.
 * Инлайн тег. Использует данные с {@link http://кодер.укр/data.php}
 * Далее будет список используемых тегов
 *
 * @author Coder UA <web@кодер.укр>
 * @version 1.0
 * @package MyPackageName
 * @category MyCategoryNews
 * @todo описание необходимых доработок
 * @example http://кодер.укр/example.php
 * @copyright Copyright (c) 2014, Coder UA
 */
class ClassName {

    /**
     * Описание переменной, если необходимо
     *
     * @var array массив данных
     */
    public $var1 = array();

    /**
     * Описание переменной, если необходимо
     *
     * @var integer очень важные данные
     */
    private $var2;

    /**
     * Краткое описание функции
     * 
     * Подробное описание функции, если необходимо 
     *
     * @param string $param1 Первый параметр функции
     * @param string $param2 Второй параметр
     * @return string
     */
    function myFuncName ($param1, $param2 = 'value') {
        
        //...
        //код
        //...

        return $var;
    }

    //...

}

Еще пример:

<?php
/**
 * Контроллер работы с новостями
 * 
 * Выполняет обработку и вывод списка новостей и подробную информацию о новости
 *
 * @package Fronend
 * @category News
 * @author Coder UA <web@кодер.укр>
 * @version 1.1
 * @copyright Copyright (c) 2014, Coder UA
 */
class NewsController extends Controller {

    /**
     * @var integer количество новостей на страницу в списке
     */
    public $limit = 10;

    /**
     * Вывод списка новостей
     *
     * @return array список новостей
     */
    public function actionIndex() {
    
        //...
        //код
        //...
    
        return $data;
    }

    /**
     * Вывод подробной информации о новости
     *
     * @param integer $id - id текущей новости
     * @return array данные о новости
     */
    public function actionDetail($id) {
    
        //...
        //код
        //...
    
        return $data;
    }

    //...

}

Описание основных тегов (дискрипторов) phpDoc

Тег Синтаксис Пример Описание
@access @access [private | protected | public] @access private
@access protected
@access public
Описывает доступ к элементу. Особой надобности в этом дискрипторе нет, т.к. перед методом(функцией) или свойством(переменной) обычно указывается область видимости.
@author @author [имя автора] [<email адрес>] @author Coder UA
@author Coder UA <web@кодер.укр>
Автор кода(элемента) и его электронная почта (не обязательно).
@category @category [описание] @category MyCategory Используется для организации групп пакетов.
@copyright @copyright [описание] @copyright Copyright (c) 2014, Coder UA Информация о правообладателе кода.
@deprecated @deprecated [<версия>] [<описание>] @deprecated
@deprecated 1.0.0
@deprecated Использует небезопасные методы.
@deprecated 1.0.0 Использует небезопасные методы.
Тег указывает на то, что код устарел. Указывается версия, начиная с которой код считается устаревшим и описание почему код устарел.
@example @example [путь] [<стартовая линия> [<количество строк>] ] [<описание>] @example myExample.php Пример выполнения метода.
@example http://example.com/myExample.php Пример выполнения метода при условии, что старт == 1.
@example "My Own Example.php" My counting.
Путь к файлу с примером использования кода. Стартовая линия - номер строки, с которой нужно отобразить пример (не обязательно). Количество строк - количество строк для представления примера от стартовой линии. Если не указано, файл примера будет показан ​​от линии старта до конца файла (не обязательно). Если нет стартовой линии, то файл примера будет представлен полностью.
@final @final @final Применяется для методов или свойств которые запрещено перегружать в дочерних классах. Также можно отметить класс который не должен быть родителем.
@filesource @filesource @filesource Тег может быть использован только в начале файла. Указывает, что необходимо вывести исходный код текущего файла.
@global @global [тип] [имя] [<описание>] @global string $gStr глобальная строчная переменная Декларирует глобальные переменные.
@ignore @ignore [<описание>] @ignore
@ignore описание почему мы игнорируем текущий элемент
Игнорирование элемента.
@internal @internal [описание] @internal Этот комментарий не будет добавлен в документацию Значение тега не будет добавлено в документацию. Можно использовать для комментариев предназначенных для тех кто работает с кодом.
@license @license [<url>] [название] @link http://кодер.укр/license.txt GNU Public License
@link GPL
Ссылка на лицензию, под которой распространяется код.
@link normal
@link [url] [<описание>]
inline
Больше информации об объекте ({@link http://кодер.укр/doc})
@link http://кодер.укр/doc дополнительная документация Указывает ссылку на документацию элемента.
@method @method [возвращаемый тип] [название]([[тип] [параметр]<, ...>]) [<описание>] @method string getStr()
@method setStr(integer $integer)
Позволяет описать магический метода __call().
@name @name [имя] @name $globalVarName Используется в связки с @global. Для отождествления.
@package @package [уровень 1]\[уровень 2]\[и т.д.] @package Yii\Documentation\API Указывает имя пакета, в который входит код (файл). Используется в начале файла или в блоке комментариев класса.
@param @param [тип] [имя] [<описание>] @param integer $value
@param integer $value описание переменной
Тег описывает входные параметры для функций и методов классов.
@return @return [тип] [<описание>] @return integer количество строк.
@return string|null строка после проверки.
Описывает возвращаемые данные функцией или методом класса. В качестве типа можно указать имя класса, phpDocumentor автоматически создаст ссылку на этот класс.
@see @see [url | метод | переменная] [<описание>] @see http://кодер.укр/doc Подробная документация.
@see MyClass::$val
@see MyClass::myFunction()
Тег указывает на то, что документация уже существует в другом докблоке. Например класс имплементирует интерфейс, который уже содержит подробный докблок. Позволяет избежать дублирование информации.
@since @since [версия] [<описание>] @since 1.0.2 Добавлен аргумент $b.
@since 1.0.1 Добавлен аргумент $a.
@since 1.0.0
Указывает на версию класса, метода или функции с которой комментируемый элемент стал доступен.
@static @static @static Указывает на то, что метод или свойство является статическим.
@subpackage @subpackage [имя] @subpackage Documentation\API Объеденяет несколько пакетов в один раздел документации. Используется с тегом @package. Применяется в начале файла или заглавном докблоке класса.
@todo @todo [описание] @todo исключить возможность вызова без авторизации Описывает необходимые доработки кода.
@throws @throws [тип] [<описание>] @throws InvalidArgumentException если элемент не массив. Указывает тип исключения, которое может быть возвращено методом или функцией.
@uses @uses [метод|переменная] [<опимание>] @uses MyClass::$items для получения счетчика. Описывает связь между текущем элементом и другим структурным элементом.
@var @var [тип] [имя] [<описание>] @var string $value строка с данными Тип, имя и описание свойства класса.
@version@version [<вектор>] [<описание>] @version 1.1
@version V. 1.4
Текущая версия.

В конечном итоге при использовании docBlock комментариев Вы получите:

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