Invalid highlighting in doc comments

[kissarat]

https://github.com/phpbb/phpbb/blob/9596db9b8869d2d9d68112ac7aadf394545d2811/phpBB/phpbb/auth/auth.php#L216

I was redirected here from github support

[infininight]

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]

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. 😄