CODEWITHSUNDEEP
phpphpdocphpdocumentor2
ReneFroger
ReneFroger

Reputation: 530

Would it make a difference to PHPdoc if I close my tags with colon (example)?

I always use colons in my phpdoc blocs. For example, instead of:

/** Some comment
 *
 *@private
 * 
 *@param string $sTable The name of the table 
 *@return bool True otherwise void
 *@example className->tableExists($sTable);
 *@since date
 */

Instead of the above, I use the following style:

/** Some comment
 *
 * @private
 * 
 * @param   : string $sTable The name of the table 
 * @return  : bool True otherwise void
 * @example : className->tableExists($sTable);
 * @since   : date
 */

You see, I prefer to divide the tags and description with colons. It's easier to read and has more style. But I wonder if this makes any difference for PHPdoc parsing the docbloc at all?

Upvotes: 0

Views: 118

Answers (2)

Jelmergu
Jelmergu

Reputation: 964

To PHPDocumentor it makes quite a difference. Testing shows the following

/**
 * Test constructor.
 * @param : string $var testvar
 *
 */

gets documented to: enter image description here

Where 

/**
 * Test constructor.
 * @param  string $var testvar
 *
 */

outputs enter image description here

It is ofcourse somewhat logical that it is that way, as it is a syntax error. If you want to make the docblock look nice, you can align the values with spaces.

/** Some comment
 *
 *@private
 *
 *@param   string $sTable The name of the table
 *@return  bool|void      True otherwise void
 *@example className->tableExists($sTable);
 *@since   date
 */

Upvotes: 2

Machavity
Machavity

Reputation: 31654

I'm not sure about PHPDoc itself, but it would make a difference to some IDEs. I tried this in PHPStorm and while @param and @var were unaffected, @return failed out.

I would be cautious using a non-standard format.

Upvotes: 0

Related Questions