Документирование кода PHP на основе DocBlock комментариев

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

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

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

• Пример использования DocBlock комментариев
• Описание тегов (дискрипторов) phpDoc

Пример использования 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

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

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