Я использую комментарий @since в своем PHP-коде. У меня есть вопрос о его использовании, хотя. Скажем, у меня есть функция, выполняющая определенную задачу, и она реализована в версии 1.0.
Итак, в настоящее время у меня есть @since 1.0.
Теперь я иду вперед и меняю имя функции, хотя код внутри остается прежним. Должен ли он теперь говорить @since 3.0 (текущая версия) или оставаться @since 1.0?
Имя функции не существовало в версии 1.0, поэтому @since должно быть 3.0. Неважно, что функция с другим именем предоставляла ту же функциональность в старой версии; вы не сможете использовать новое имя в старой версии. В документах говорится:
Используйте
@sinceдля документирования изменений, например, «Эта функция была частью этого пакета, начиная с версии 2.0».
Цель @since — сообщить кому-либо, использующему ваш пакет, что «начиная с версии x существует функция с именем foo. Если вы измените foo на bar в v3, но оставите @since как v1, тогда ваши документы будут неверно заявляют, что безопасно вызывать bar() в версии 1. На самом деле в версии 1 не было bar(), и вызов выдавал бы ошибку.
Вы также можете сохранить заглушку функции со старым именем (которое просто вызывает настоящую функцию) и пометить ее как @deprecated.
foo() извлекает некоторый набор данных, вы можете переписать функцию, чтобы она возвращала данные из кеша, вместо того, чтобы каждый раз выполнять дорогостоящие запросы к базе данных при вызове функции. Код, использующий ваш API, не заботится о том, как извлекаются данные, а только о том, чтобы вы предоставили правильные данные. Конечно, вы можете заметить изменение в описании функции: Начиная с vX, эта функция кэширует возвращаемый набор данных. См. {@link clearFoo()}, если вам нужно очистить кешированные данные.
- person josh3736; 08.03.2013
foo() удаляет данные, а не извлекает их) или ее подпись (добавляя необязательные аргументы), вам следует подумать об использовании другого имени.
- person josh3736; 08.03.2013
Тег @since указывает, в какой версии стали доступны связанные структурные элементы.
Синтаксис
@since [version] [<description>]
Тег @since можно использовать для указания, начиная с какой версии стали доступны структурные элементы.
Эта информация может использоваться для создания набора документации по API, где потребителю сообщается, какая версия приложения необходима для конкретного элемента.
Версия ДОЛЖНА следовать тем же правилам, что и вектор тега @version, и МОЖЕТ иметь описание для предоставления дополнительной информации.
Этот тег может встречаться несколько раз в PHPDoc. В этом случае каждое вхождение рассматривается как запись в журнале изменений. РЕКОМЕНДУЕТСЯ, чтобы вы также предоставили описание для каждого такого тега.
Пример
/**
* @since 1.0.1 First time this was introduced.
*
* @return integer Indicates the number of items.
*/
function count()
{
<...>
}
/**
* @since 1.0.2 Added the $b argument.
* @since 1.0.1 Added the $a argument.
* @since 1.0.0
*
* @return void
*/
function dump($a, $b)
{
<...>
}
т.к. это тег phpDoc
Теги PHPDoc работают с некоторыми редакторами для отображения дополнительной информации о фрагменте кода. Разработчикам, использующим эти редакторы, полезно понять, для какой цели и где они будут использовать их в своем коде.
Соглашение о разрешении блоков PHPdoc состоит в том, чтобы иметь информацию @since (даже если она недоступна в то время) и информацию @package, которая всегда должна быть «WordPress», если это не внешняя библиотека. лайк
/**
* ... Description(s) here
*
* @package WordPress
* @since 2.1 or {@internal Unknown}}
*
* ... More information if needed.
*/
Пожалуйста, прочитайте следующие статьи для получения дополнительной информации о тегах phpDoc.
Документировать, когда (в какой версии) элемент был впервые добавлен в пакет
Теги phpDocumentor — Как использовать теги в DocBlocks
