Question

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

所以我现在有@since 1.0。

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

Answer 1

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

使用@since来记录修订版，例如“自2.0版以来此函数已成为此软件包的一部分”

@since的目的是告诉使用您的软件包的人“自 x 版本以来，存在名为foo的函数。如果您去更改{{1}在v3中转到foo但将bar保留为v1，那么您的文档会错误地声明在v1中调用@since是安全的。事实上，没有bar() v1，调用会引发错误。

您可能还会考虑使用旧名称（仅调用实际函数）保留函数存根，并将其标记为@deprecated。

Answer 2

@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)
 {
     <...>
 }

Answer 3

因为是phpDoc代码

PHPDoc标签与一些编辑器一起使用，以显示有关一段代码的更多信息。对于使用这些编辑器的开发人员来说，了解他们在代码中使用它的目的和位置非常有用。

允许PHPdoc块的约定是@since信息（即使当时不可用）和@package信息，除非它是外部库，否则它应始终为“WordPress”。喜欢以下

/**
 * ... Description(s) here
 *
 * @package WordPress
 * @since 2.1 or {@internal Unknown}}
 *
 * ... More information if needed.
 */

有关phpDoc标签的更多信息，请阅读以下文章

PHPDocumentor 0.4.1

Document when (at which version) an element was first added to a package

phpDocumentor Tutorial

phpDocumentor tags - How to use tags in DocBlocks

@since - phpDocumentor

在PHP代码中使用@since

3 个答案: