I have multiple todo items I want to add for a function.
What is the correct way to add them in a phpDoc comment block?
I understand that I should use the @todo tag. But I am unsure of whether I should use a single @todo tag per item, or one @todo tag for the whole list.
Zero or more @todo tags is valid.
@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()
{
<...>
}
From the standard (emphasis mine):
The
@todotag is used to indicate that an activity surrounding the associated "Structural Elements" must still occur. Each [@todo] tag MUST be accompanied by a description that communicates the intent of the original author; this could however be as short as providing an issue number.
The way I read this paragraph, there may be multiple @todo tags (since the standard refers to "each" instead of "the" tag) and each tag represents a single incomplete behavior (since it reads "an activity", instead of "activities").
This, to me, makes the most sense, as each @todo acts as an item in an overall check list. As you complete an item, you "check it off" by deleting the todo item. This would appear very clearly as a line delete in your version control diffs.
However, these are simply annotations, so you may choose of course to ram multiple tasks into one.
