Search code examples
phpcommentsstandardspear

what is the purpose of the extra asterisks in php comments?

I've (finally) been reading up on PEAR (php) coding standards.

What is the purpose of commenting like this:

/** 
*   Here is my comment
*   I Wrote this in a haiku
*   But why put the stars?
*/

As opposed to this:

/* 
   Here is a comment
   No haiku or 
   anything special, but it still works!
*/
Solution

  • The /** stuff */ document is also referred to as DocBlock notation.

    It's used to document PHP functions, classes, etc.

    /** 
* A test function
*
* @param  foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }

    Some editors make good use of this to perform their Code Insight feature, a very powerful tool that reduces the time you have to spend looking at your old function declarations. Aptana and Zend Studio have this feature, probably others as well.

    You can also use it in combination with Reflection to do some sort of AOP, doing runtime inspection of the DocBlock above your declarations. In fact, Doctrine uses it to build an object attribute map for their "Active Record" implementation.