textmate/php.tmbundle

Invalid highlighting in doc comments

kissarat opened this issue · 2 comments

infininight commented

So the highlighting here was designed with PHPDoc in mind, though I believe there are other documentation generators for PHP. According the the PHPDoc documentation each line should start with a *, so the invalid color is there is denote this restriction.

Does PHPBB use a different documentation generator or is this restriction not as ironclad as the documentation suggests?

Tenzian commented

There's a good discussion about this issue (which also cropped up in sublime text) at sublimehq/Packages#68.

The solution there was:

Multiline comments that start with /** are no longer an error if each line does not start with *,
however, PHPDoc @ keywords are also not highlighted in that situation.

The particular instance of this style of doc block not being invalid I've encountered is zircote/swagger-php#326 where you're trying to use descriptions longer than PSR-2 recommendations for line length and keep both swagger-php and php cs happy at the same time. 😄