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標籤用來指示圍繞相關「結構元素」的活動仍然必須發生。 每個[@todo]標籤必須附有描述，以傳達原作者的意圖;這可能與提供問題編號一樣短。

我讀這個段落中的方法，可以有多個@todo標籤（因爲標準是指「每個」，而不是「該」標籤），並且每個標籤表示單個殘缺行爲（因爲它讀取「的活動「，而不是」活動「）。

對我來說，這是最有意義的，因爲每個@todo都作爲整個檢查列表中的項目。當你完成一個項目時，你可以通過刪除待辦事項來「檢查它」。這會在版本控制差異中作爲行刪除而顯得非常清晰。

但是，這些只是註釋，因此您可以選擇將多個任務合併爲一個。