Урок - Теги в phpDocumentor

Главная » Курсы » Курс Документирование PHP-кода » Урок - Теги в phpDocumentor

Обучающий онлайн курс
Документирование PHP-кода

Лицензия: Копирование запрещено.

Теги - это зарезервированные слова, используеммые для расширения возможностей PHPDoc-коментариев.

Различаются два вида тегов:

  • обычные теги.
  • линейные (inline) теги.

Обычне теги идут в начале строки и имеет следующий вид:

@<тег> <описание>
  • <тег> - имя тега (одно из зарезервированных)
  • <описание> - инофрмаци относящаяся к тегу

Например:

/**
 * @param string $login Логин пользователя
 */

Ниже приведен список основных тегов:

  • @author - указывает автора.
  • @version - указывает версию файла. часто автоматически.
  • @package - указывает имя пакет.
  • @subpackage - указывает имя подпакета.
  • @var - указывает описание к переменной или свойству класса.
  • @param - описывает аргумент функции или метода
  • @return - описывает значение возвращаемое функцией
  • @todo - заметка, о будущем изменении кода

Линейные (inline) теги используются внтури коментария и должны заключаться в {} (фигурные скобки):

/**
 * Это линейный тег {@source 3}.
 */

Тег @author

/**
 * @author Чебурашка
 * @author Генадий <gandy@site.zzz>
 */

Тег @version

/**
 * @version $Id$
 */

Тег @package и @subpackage

Тег @package и @subpackage используются для указания структуры проекта:

/**
 * @package Новости
 * @package Управление
 */

Тег @var

Тег @var указывает описание к переменной или свойству класса. Описание в теге @var используется для автозаполнения в IDE.

/**
 * @var <тип переменной> <описание>
 */

Пример:

/**
 * @var classUser Владелец, экземпляр класса
 */
$acount = null;

Тег @param

Тег @param указывает описание к аргументам функций и методам классов. Описание в теге @param используется для автозаполнения в IDE.

/**
 * @param <тип переменной> $имя_переменой <описание>
 */

Пример:

/**
 * @param classUser $user Пользователь пополнивший баланс
 * @param int $sum Сумма пополнения
 */
public function add(classUser $user, $sum){}

Тег @return

Тег @return указывает описание к возвращаемому значению в функциях и методах классов.

/**
 * @return <тип переменной>
 */

Пример:

/**
 * @return bool Результат работы.
 */
public function add(classUser $user, $sum){
	return TRUE;
}

Тег @todo

Тег @todo указывает заметку, о будущем изменении кода. Некоторые IDE позволяют редактировать этот тег через интерфейс.

/**
 * @todo <задача на будущее>
 */

Пример:

/**
 * @todo Добавить возможность указания пользователя через ID
 */
public function add(classUser $user, $sum){
	return TRUE;
}