An evil, nasty bug bit me today. For a long time, I’ve calculated the number of “pure” rows of PHP source code from PHP scripts. To accomplish this, I looped through all the tokens and removed any instance of T_COMMENT.
In the manual, at https://www.php.net/manual/en/tokens.php , it says:
T_COMMENT // or #, and /* */ comments
It turns out that this did not delete some kind of fancy alternative-style comment, apparently called “PHPDoc style comments”. On the same page, further down (which I never looked for, because I had no idea they existed), it says:
T_DOC_COMMENT /** */ PHPDoc style comments
Now, my code works, because I account for both kinds.
However, I still wonder what a “PHPDoc style comment” is supposed to be, and why they are not considered part of T_COMMENT.
Frustratingly, the “PHPDoc style comments” hyperlink on that manual page just links to a generic “comments” page which doesn’t mention “PHPDoc” anywhere!
So, what is it? Why is it considered a special kind of comment? Why isn’t it documented? Why must everything in this life be a complete damn mystery?!
These kind of comments are used to read by documentation tools, which analyze your source code and generate documentations about your functions and classes. As an example the phpDocumentor is such a tool to generate documentations, similar to javadoc.