我在我的 PHP 代码中使用 @since 注释。我有一个关于它的使用的问题。假设我有一个执行特定任务的函数，它已在 1.0 版中实现。
所以我目前有@since 1.0.
现在我继续更改函数的名称，尽管里面的代码保持不变。现在应该说@since 3.0（当前版本）还是保持@since 1.0？
问问题
3580 次
3 回答
22
函数名在 1.0 中不存在，因此@since应该是 3.0。不同名称的函数在旧版本中提供相同的功能是无关紧要的。您将无法在旧版本中使用新名称。文档说：
用于
@since记录修订，如“此功能自 2.0 版以来一直是此软件包的一部分”
的目的@since是告诉使用您的包的人“从版本x开始，存在一个名为的函数foo。如果您在 v3 中更改foo为但保留为 v1，那么您的文档将错误地声明在 v1 中调用是安全的。事实上, v1 中没有，调用会抛出错误。bar@sincebar()bar()
您还可以考虑使用旧名称（仅调用实际函数）保留函数存根，并将其标记为@deprecated.
于 2013-03-05T16:43:50.263 回答
3
@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)
{
<...>
}
于 2013-03-12T16:13:18.490 回答
0
因为是一个phpDoc标签
PHPDoc 标签与一些编辑器一起工作，以显示有关一段代码的更多信息。对于使用这些编辑器的开发人员来说，了解他们在代码中使用它的目的和位置很有用。
允许 PHPdoc 块的约定是具有 @since 信息（即使当时不可用）和 @package 信息，除非它是外部库，否则应始终为“WordPress”。喜欢以下
/**
* ... Description(s) here
*
* @package WordPress
* @since 2.1 or {@internal Unknown}}
*
* ... More information if needed.
*/
请阅读以下文章以获取有关 phpDoc 标签的更多信息
于 2013-03-12T12:55:50.197 回答