Home » Php » php – What exactly are "PHPDoc style comments"?

php – What exactly are "PHPDoc style comments"?

Posted by: admin February 25, 2020 Leave a comment

Questions:

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?!

How to&Answers:

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.