在PHP代码中使用@since

Question

我在PHP代码中使用@since注释.我对它的使用有疑问.假设我有一个执行特定任务的函数,它已在1.0版本中实现.

所以我现在有@since 1.0.

现在我继续更改函数的名称,尽管里面的代码保持不变.它应该现在说@since 3.0(当前版本)还是@since 1.0？

Answer 1

函数名称在1.0中不存在,因此@since应为3.0.一个不同命名的函数在旧版本中提供相同的功能是无关紧要的; 您将无法在旧版本中使用新名称.该文件说:

使用@since记录的修改,如"此功能已自2.0版本的软件包的一部分"

目的@since是告诉使用你的软件包的人"从版本x开始,这是一个名为fooexists 的函数.如果你在v3中更改foo为bar但是保留@since为v1,那么你的文档会错误地声明bar()在v1中调用是安全的.事实上,bar()在v1 中没有,并且调用会抛出错误.

您还可以考虑使用旧名称(仅调用实际函数)并标记它来保留函数存根@deprecated.

Answer 2

@since 标签指示关联的结构元素在哪个版本中可用。

\n\n

句法

\n\n

@since [version] [<description>]\n

\n\n

@since 标签可用于指示自哪个版本起特定的结构元素变得可用。

\n\n

此信息可用于生成一组 API 文档，其中告知消费者特定元素需要哪个应用程序版本。

\n\n

版本必须遵循与 @version tag\xe2\x80\x99s 向量相同的规则，并且可以有一个描述来提供附加信息。

\n\n

该标记可以在 PHPDoc 中出现多次。在这种情况下，每次出现都被视为更改日志的条目。建议您还为每个此类标签提供描述。

\n\n

例子

\n\n

  /**\n  * @since 1.0.1 First time this was introduced.\n  *\n  * @return integer Indicates the number of items.\n  */\n function count()\n {\n     <...>\n }\n\n /**\n  * @since 1.0.2 Added the $b argument.\n  * @since 1.0.1 Added the $a argument.\n  * @since 1.0.0\n  *\n  * @return void\n  */\n function dump($a, $b)\n {\n     <...>\n }\n

\n