Simplify syntax highlighting for PHPDoc

[jrmajor]

This is how a complex docblock is currently highlighted:

For comparison, this is how a JSDoc is highlighted:

I would like the same highlighting rules to apply to PHPDoc: one color for tag (eg. @param), second color for type and third color for param name / generic type definition.

[jakubmisek]

This is a bug in vscode's builtin php support.

With PHP Tools extension this should look different already - not sure why you don't see it :/

I'll send a screenshot in a few hours how's it suppose to look like.

[jakubmisek]

May I ask you to try a different theme? Maybe we use a nonstandard semantic token color.

[jrmajor]

The color theme in the screenshot is GitHub Light. I checked with Dark Modern and it looks like the same tokens are highlighted, just with different colors.

Edit: I've tried completely uninstalling PHP Intelephense (before it was just disabled), updating PHP Tools to pre-release version and saving the file to disk (it was a temporary file before). Still looks the same.

[jrmajor]

After randomly reopening the file, force retokenizing, making some changes to the file and then reverting them, the syntax highlighting changed:

Argument names now have distinct color, but type highlighting is still chaotic. My request to make all types in docblocks have one color would still be relevant.

BTW, I think that it's the parentheses in the last two params that cause following tags to be blue instead of red.

(here is the code from the example)

<?php

/**
 * Some comment
 * @template T of string|int
 * @param array{foo: T, bar: int} $arrayShape
 * @param object{'foo': int, "bar"?: string} $objectShape
 * @param Foo<int, string, bool> $genericClass
 * @param array<string, int> $genericArray
 * @param Foo::STATUS_* $constantEnum Some comment
 * @param int[] $simpleArray Some comment
 * @param non-negative-int $nonNegativeInt
 * @param int<min, 5> $genericInt
 * @param callable(int &$foo, string ...$bar): void $callable
 * @param (Foo&Bar)|null $intersection
 * @return void some comment
 */
function foo(
    array $arrayShape,
    object $objectShape,
    Foo $genericClass,
    array $genericArray,
    int $constantEnum,
    int $simpleArray,
    int $nonNegativeInt,
    int $genericInt,
    $intersection,
    callable $callable,
): void {
}

[jakubmisek]

We've implemented colorization for doc block keywords. It overrides the VSCode default tokens; So now it looks like below:

[jrmajor]

Thank you for the explanation. Unfortunately, this really doesn't work for me – I find docblocks very distracting with the current highlighting. Using one color for the entire type in docblock is what is done by built-in JS support with JSDoc, so it feels like it's not unreasonable to expect third party plugins to follow the precedence, although I understand that some people may find more granular highlighting useful. Maybe you could consider adding a setting for that, something like php.granularDocblockHighlighting, so that it could be disabled?

[jakubmisek]

I'm not sure I understand correctly. Here we "fixed" the inconsistency of built-in colors (VSCode does not understand the syntax of PHPDoc well, and breaks the colors). Plus we added semantic colors for class names.

Comparison
<-- without PHP Tools | with PHP Tools (upcoming pre-release) -->

Sadly we can't "remove" colors from PHPDoc.

[jrmajor]

Here we "fixed" the inconsistency of built-in colors (VSCode does not understand the syntax of PHPDoc well, and breaks the colors).

Sorry, I assumed that VS Code does not highlight PHPDoc at all.

Sadly we can't "remove" colors from PHPDoc.

Oh, that's bad news. I'll try raising an issue in VS Code repo then. Thank you for your help!

[jakubmisek]

That is what we hoped for as well; there are several issues in VSCode's built-in PHP grammar, and I'm pretty sure they won't/can't fix it.

• their grammar tries to colorize keywords in PHPDoc, but
• the (extended) syntax used by PhpStan, Psalm, and others grew and got too complex
• vscode probably can't keep up and won't support the extended syntax

We can however provide a different color, for example, we can dim type names or make them with a single color. If that would help?

[jrmajor]

We can however provide a different color, for example, we can dim type names or make them with a single color. If that would help?

That's exactly what my request was about! I would like the entire type definition to have a single color, just like for JSDoc.

To avoid confusion, here's a mockup of how perfect highlighting for me would look (this is not a screenshot from VS Code, I've just colored this fragment manually in TextEdit):

[jakubmisek]

I see! There were too many various issues, we'll get there.

I'll add a setting for phpdoc "uniform" types color, something like "php.docblock.colors": default|simple ?

---

"php.docblock.colorMode": null|"simple"|"fallback"

[jrmajor]

Sounds good to me, I'll leave the naming up to you :)

[jakubmisek]

Implemented, setting "php.docblock.colorMode".

Will be available in the next update/pre-release.

Thanks for the suggestion!