with stuff like that can't it be merged into the normal @var phpdoc block?
I believe @var and @return phpdoc definitions support stuff like class-string and generics

at least phpstan understands it. don't know how our api docs generator handles it though

We would have to check how far also IDE are in understanding the more stan based annotations.

laravel uses it for quite some time
https://github.com/laravel/framework/blob/ff4f657ca9d9af36e021a67c6eeb97949a0e27d0/src/Illuminate/Support/Facades/Exceptions.php#L45

e.g. look at this insane definition
https://github.com/laravel/framework/blob/ff4f657ca9d9af36e021a67c6eeb97949a0e27d0/src/Illuminate/Database/Eloquent/PendingHasThroughRelationship.php#L50-L63

Yeah, thats exactly how you dont do it :) Ever.
It means you lose all capability of your IDE to give you feedback at real time.
Especially since it is easy enough to add them prefixed on top for STAN tools to also work, and basically have the perfect tradeoff.

with stuff like that can't it be merged into the normal @var phpdoc block?

Yes it can be merged. These annotations most likely predate the support for this form in phpstorm. Hence the prefix.

I ran a simple replace of @psalm- to @phpstan-. Not going to review each annotation manually :) We can clean them up as and when anyone is working on that part of the code.

At least with the free PHP-Tools VS Code extension it does autocompletion correctly for class-string definitions

I can't tell how other LSP's handle that (like Neovim's) but PHPStorm definitely understands this.

class-string is fine
I think the other examples you showed are bit too crazy :)