phpDoc中应该如何使用@version？

Question

我一直在阅读phpDoc 和代码 cmets。

我的理解是否正确，@version 可以在一个项目中多次使用。

以上链接中的文档通过声明“@version 标记可用于指示结构元素的当前版本”表明了这一点。

例如，在插件中，主插件本身可能是 1.0.0 版本，但该插件的一个类可能是 3.0.0 版本。如果是这样，@since 是否与之前使用的 @version 标记直接相关？

Answer 1

您在“@version 可以在一个项目中多次使用”中是正确的。标签是故意灵活的，可以从一个极端（整个包的版本，所以所有标签显示相同的值）到另一个极端（每个类/方法/函数/任何东西都有自己的版本#并更改）历史，所以 v1.2.3 的一个类可以有十个方法，它们都显示了它们自己不同的版本号）。但是，总的来说，我相信我从未见过比“可安装库/包/应用程序级别”更精细地使用版本的情况。

关于@since 标记...无论您对给定元素使用@version 标记的任何样式，@since 标记都代表该元素首次引入的版本#。对此的一种变体是您使用 @since 标记（如更改日志），因此您在同一元素上有多个 @since 标记（请参阅此处的 dump() 函数示例 -- http://docs.phpdoc.org/references/phpdoc/tags/since.html）。

我对如何使用这些标签的建议： -“版本”是包/库/应用程序的整体发布版本，表示它们都在一个版本控制存储库中 - 我只会将@version 标签放在文件级文档块、类级文档块和独立函数文档块中 - 我只会在 API 级别 类和方法上使用@since 标签

很容易过度使用这些标签，从而使标签值的维护成为一场噩梦。