phpDoc中有多个@todo

Question

我想为一个功能添加多个待办事项。

在phpDoc评论栏中添加它们的正确方法是什么？

我知道我应该使用@todo标签。 但我不确定是否应该为每个项目使用一个@todo标记，或者为整个列表使用一个@todo标记。

Answer 1

零个或多个@todo标签有效。

PSR-5: PHPDoc

语法

@todo [description]

实施例

/**
 * Counts the number of items in the provided array.
 *
 * @todo add an array parameter to count
 *
 * @return int Returns the number of elements.
 */
function count()
{
    <...>
}

Answer 2

From the standard (emphasis mine)：

  

@todo标记用于表示相关的＆＃34;结构元素＆＃34;周围的活动。必须仍然发生。 每个[@todo]标记必须附有传达原作者意图的描述;然而，这可能与提供问题编号一样短。

我读这个段落的方式可能有多个@todo标签（因为标准是指＆＃34;每个＆＃34;而不是＆＃34;＆＃34;标签），每个标签代表一个不完整的行为（因为它读取＆＃34;一个活动＆＃34;而不是＆＃34;活动＆＃34;）。

对我来说，这是最有意义的，因为每个@todo都充当整体检查列表中的项目。当您完成一件物品时，您可以检查它＆＃34;删除待办事项。这可以非常清楚地显示为版本控制差异中的行删除。

但是，这些只是注释，因此您可以选择将多个任务合并为一个。