如何使用PHPDoc为PHP代码块添加last-modified / version？

Question

我正在开发一个WP主题，并且我正在使用PHPDoc评论我的PHP代码。我想添加大型代码块的版本，以便客户知道它何时更新。

我们说我发布了1.0.0的初始版本，然后我在版本1.0.2中更新了一些代码。如何记录代码已更改？这是否正确：

/**
 * Code block #1
 * 
 * @since ThemeVersion 1.0.0
 * @version 1.0.2
 */

我不确定这是使用@version的正确方法，因为另一方面，我有另一种情况，在更新后没有更改另一个代码块：

/**
 * Code block #2
 * 
 * @since ThemeVersion 1.0.2
 * @version 1.0.0
 */

所以不确定这是否有意义..请让我知道你的想法。

谢谢。

Answer 1

您的使用案例是两种标签组合的合理使用。

因此，我希望您在代码块＃1中的使用意味着：

• 此块是在Theme v1.0.0
中创建的
• 此块最后由Theme v1.0.2
修改

（请注意，消费者使用的当前主题版本可能是v2.0.0，但这些标记值仍然意味着它们的含义 - 即使此已安装主题是v2.0.0，代码块＃1最初是在v1.0.0中添加的，最后一次在v1.0.2中更改了

现在，在您的代码块＃2上：

• @since ThemeVersion 1.0.2应该告诉我该块首次创建在Theme v.1.0.2中
• 但@version 1.0.0告诉我它最后被v1.0.0修改过......但这不对，因为直到v1.0.2它才会在代码中出现。

（如果您将两个标记值都设置为1.0.0，那么对我来说＆＃34;块＃2是在v1.0.0中创建的，尚未更改）。