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

Question

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! */ 

Answer 1

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.

Answer 2

The double asterisk comment is used sometime by certain documentation systems. The documentation system will proccess the block and look for certain keywords like @author or @var.

Single asterisk comments wil be treated as // comments.

See PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html